Opik 离线回退与消息重放：网络断了，追踪数据也不丢- 惊觉

做 LLM 应用追踪的人，大概都遇到过这种情况：服务跑得好好的，突然网络抖了一下，或者 Opik 服务端短暂不可达，结果那段时间的 trace、span、反馈分数全丢了。事后想复盘，发现数据缺口正好卡在出问题的时间段，非常尴尬。Opik 的 Python SDK 内置了一套离线回退机制，专门解决这个问题。它会在网络中断时自动把消息存到本地 SQLite 数据库，等连接恢复后再悄悄重放，整个过程不需要改应用代码。

这套机制是 Python SDK 独有的，默认开启，不用额外配置。下面从原理、支持的消息类型、配置调优、恢复时间估算和故障排查几个方面，把它讲清楚。

一、它到底怎么工作

离线回退完全在后台运行，分三个阶段：检测、存储、重放。

检测阶段：SDK 里有一个轻量的后台线程 OpikConnectionMonitor，会定期 ping Opik 服务端的 /is-alive/ping 端点。如果 ping 失败，或者发送消息时遇到连接错误，SDK 就把连接标记为不可用。

存储阶段：连接不可用期间，每一条新消息都会立刻写入本地 SQLite 数据库，而不是走网络发送。数据库放在系统临时目录里。如果某条消息在连接断开时正在发送途中，它会被重新标记为失败，然后加入同一个存储。

重放阶段：当 OpikConnectionMonitor 检测到服务端重新可达，一个 ReplayManager 线程会按配置的批次读取所有已存储的消息，重新注入 SDK 的正常处理管道。之后，它们就像普通消息一样被投递到服务端。

整个流程可以用下面这张图概括：

Application code
      │
      ▼
 Opik SDK client
      │
      ├─ Connection OK? ──Yes──▶ Send to REST API ──Success──▶ Done
      │                                           └─Failure──▶ Write to SQLite
      │
      └─ Connection down? ───▶ Write to SQLite as "failed"
                                       │
                                 ConnectionMonitor
                                 detects recovery
                                       │
                                       ▼
                                 ReplayManager reads
                                 failed messages in
                                 batches and resubmits

SQLite 数据库会在 SDK 关闭时自动清理。已经投递成功的消息，一旦服务端确认收到，就会从数据库里删除。所以本地不会无限堆积数据。

二、哪些消息类型受保护

不是所有操作都走这套回退机制，但覆盖的范围已经比较广。下面这些 SDK 操作产生的消息类型，都在离线回退的保护范围内：

操作	存储的消息类型
`client.trace()`	`CreateTraceMessage` / `CreateTraceBatchMessage`
`trace.update()`	`UpdateTraceMessage`
`trace.span()` / `client.span()`	`CreateSpanMessage` / `CreateSpansBatchMessage`
`span.update()`	`UpdateSpanMessage`
`client.log_traces_feedback_scores()`	`AddTraceFeedbackScoresBatchMessage`
`client.log_spans_feedback_scores()`	`AddSpanFeedbackScoresBatchMessage`
`client.log_threads_feedback_scores()`	`AddThreadsFeedbackScoresBatchMessage`
Guardrail evaluations	`GuardrailBatchMessage`
`experiment.insert()`	`CreateExperimentItemsBatchMessage`
File attachments	`CreateAttachmentMessage`

简单说，创建 trace、更新 trace、创建 span、更新 span、记录反馈分数、线程反馈分数、护栏评估、实验条目、文件附件，这些都会在断网时被暂存。对于大多数使用场景，核心数据都能保住。

三、配置方式：环境变量和配置文件

离线回退开箱即用，默认值已经比较合理。但你可以根据环境调整它的行为。有两种配置途径：环境变量和 ~/.opik.config 文件。

环境变量

在启动应用之前设置这些变量：

# How often (seconds) to ping the server to check connectivity (default: 10)
export OPIK_CONNECTION_MONITOR_PING_INTERVAL=10

# Timeout (seconds) for each connectivity ping (default: 5)
export OPIK_CONNECTION_MONITOR_CHECK_TIMEOUT=5

# Number of failed messages to replay in one batch after recovery (default: 50)
export OPIK_REPLAY_BATCH_SIZE=50

# Delay (seconds) between replay batches to control throughput (default: 0.5)
export OPIK_REPLAY_BATCH_REPLAY_DELAY=0.5

# How often (seconds) the replay manager thread checks connection state (default: 0.3)
export OPIK_REPLAY_TICK_INTERVAL=0.3

配置文件

也可以把这些参数写进 ~/.opik.config 的 [opik] 段：

[opik]
url_override = https://www.comet.com/opik/api
api_key = <your-api-key>

# Offline fallback tuning
connection_monitor_ping_interval = 10
connection_monitor_check_timeout = 5
replay_batch_size = 50
replay_batch_replay_delay = 0.5
replay_tick_interval = 0.3

两种方式都行，环境变量适合临时调整或容器化部署，配置文件适合持久化设置。

四、配置参数参考

下面这张表把每个参数、对应的环境变量、默认值和含义都列出来了：

参数	环境变量	默认值	说明
`connection_monitor_ping_interval`	`OPIK_CONNECTION_MONITOR_PING_INTERVAL`	`10`	两次服务器健康检查 ping 之间的秒数。值越小，检测中断越快，但网络流量稍多。
`connection_monitor_check_timeout`	`OPIK_CONNECTION_MONITOR_CHECK_TIMEOUT`	`5`	等待 ping 响应的秒数，超过就认为服务器不可达。
`replay_batch_size`	`OPIK_REPLAY_BATCH_SIZE`	`50`	单批重放的存储消息数量。内存受限环境可以调小。
`replay_batch_replay_delay`	`OPIK_REPLAY_BATCH_REPLAY_DELAY`	`0.5`	重放批次之间的暂停秒数。调大可以降低恢复时对服务器的压力。
`replay_tick_interval`	`OPIK_REPLAY_TICK_INTERVAL`	`0.3`	重放管理线程循环之间的秒数。值越小，SDK 对连接恢复的反应越快。

这些默认值在大多数场景下够用。如果你的应用有特殊需求，可以按下面的建议调。

五、针对不同环境调优

高吞吐应用

如果你的应用每秒产生大量 trace，中断期间积压的消息会很多。为了在恢复后快速重放，可以增大批次、减小批次间延迟：

export OPIK_REPLAY_BATCH_SIZE=200
export OPIK_REPLAY_BATCH_REPLAY_DELAY=0.1

这样每批处理 200 条，批间只等 0.1 秒，整体重放速度会快很多。

内存受限环境

如果内存比较紧张，重放时从数据库读取消息会占用内存。可以减小批次、增大延迟：

export OPIK_REPLAY_BATCH_SIZE=10
export OPIK_REPLAY_BATCH_REPLAY_DELAY=1.0

每批只读 10 条，批间等 1 秒，内存压力小，但重放时间会拉长。

慢或不可靠网络

如果网络时断时续，可以缩短 ping 间隔，让 SDK 在中断开始后更快停止尝试发送：

export OPIK_CONNECTION_MONITOR_PING_INTERVAL=5
export OPIK_CONNECTION_MONITOR_CHECK_TIMEOUT=3

ping 间隔从 10 秒降到 5 秒，超时从 5 秒降到 3 秒，检测更灵敏。

快速恢复检测

如果想尽量缩短服务器恢复后到重放开始之间的延迟：

export OPIK_CONNECTION_MONITOR_PING_INTERVAL=5
export OPIK_REPLAY_TICK_INTERVAL=0.1

ping 间隔 5 秒，重放管理线程每 0.1 秒检查一次连接状态，反应更快。

六、恢复时间估算

连接恢复后，重放积压消息的大致时间可以用这个公式估算：

replay_time ≈ ceil(failed_messages / replay_batch_size) × replay_batch_replay_delay

举个例子：500 条存储消息，默认设置（batch_size=50，delay=0.5 s）：

ceil(500 / 50) × 0.5 = 10 × 0.5 = 5 seconds

大约 5 秒重放完。如果积压更多，或者批次更小，时间会相应增加。这个公式可以帮你判断是否需要调整参数。

七、优雅降级

如果本地 SQLite 数据库本身不可用，比如临时目录不可写，SDK 会记录一条警告，然后继续运行，只是没有离线回退。之后如果再发生中断，追踪数据会丢失，但应用不会崩溃。

这里有一个警告：确保运行 SDK 的进程对系统临时目录有写权限。大多数系统上是 /tmp，或者 tempfile.gettempdir() 返回的路径。

八、故障排查

恢复后消息没有重放

验证连接：运行 opik healthcheck，确认 SDK 能连上服务器。
检查 ping 间隔：SDK 可能需要最多 connection_monitor_ping_interval 秒才能检测到服务器恢复。默认是 10 秒，所以服务器恢复后至少等 10 到 15 秒，再判断重放是否发生。
**调用 **client.flush()：显式 flush 客户端会立即触发一次重放尝试，并等待所有待处理消息投递完成。

积压太大，重放太慢

参考高吞吐调优部分，增大 OPIK_REPLAY_BATCH_SIZE，减小 OPIK_REPLAY_BATCH_REPLAY_DELAY。

日志里出现数据库错误

如果看到类似 "Some network resiliency features were disabled" 的日志，说明 SQLite 数据库初始化失败。检查临时目录是否可写，磁盘空间是否足够。

开启调试日志

想看到详细的重放活动，在导入 opik 之前开启调试日志：

export OPIK_FILE_LOGGING_LEVEL=DEBUG
export OPIK_LOGGING_FILE=/tmp/opik-debug.log

然后查看 /tmp/opik-debug.log，搜索 replay_manager 和 db_manager 相关的条目。

九、写在最后

网络中断不是小概率事件，尤其是在分布式系统、云环境、或者跨区域调用中。如果没有离线回退，这段时间的追踪数据就是空白，事后分析、计费、效果评估都会受影响。Opik 的这套机制把复杂度封装在 SDK 内部，默认开启，自动存储、自动重放、自动清理。你需要做的只是了解它的行为，必要时调几个参数。对于生产环境，建议至少确认临时目录可写，并且知道怎么开调试日志。数据不丢，心里才踏实。

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/oscar999/article/details/166373868

Opik 离线回退与消息重放：网络断了，追踪数据也不丢