指标
模型调用观测单元¶
每个 openclaw.model.call span 通过 openclaw.model_call.observation_unit 标识其生命周期所度量的内容:
request- 一个可观测的模型/提供商请求。原生嵌入式模型调用使用此单元,并且导出器会将缺失值视为request,以兼容较旧或外部发射器。turn- 一个不透明的 agent CLI 轮次,其中可能包含隐藏的模型请求、重试、工具工作或后台工作。Claude Code CLI 和 Codex app-server 调用使用此单元。
两个单元都保持为模型调用 span,以便 trace 后端可以渲染模型输入、输出、用量和层级。请求 span 使用由 API 派生的 GenAI 操作(chat、generate_content 或 text_completion),而 turn span 使用 gen_ai.operation.name = invoke_agent。两者都贡献到 gen_ai.client.operation.duration,其中操作名称将直接请求延迟与完整轮次延迟区分开。OpenClaw 的 OTEL 模型调用指标也包含 openclaw.model_call.observation_unit;Prometheus 模型调用指标暴露等效的 observation_unit 标签。
请求级遥测还覆盖原生后台补全,包括会话标题、Activity 摘要和插件 runtime.llm.complete 调用。每个请求记录一个开始以及一个带时长的完成或错误;token 和成本核算仍单独位于 model.usage 中。
Claude Code CLI 模型调用保真度¶
Claude Code CLI 轮次发出一个合成的、轮次级 openclaw.model.call span。这些不是 Anthropic HTTP 请求 span。它们使用 openclaw.api = claude-code、openclaw.model_call.observation_unit = turn,并将操作标识为 gen_ai.operation.name = invoke_agent。它们通过 openclaw.transport 标识 OpenClaw 的 CLI 边界:
stdio- 一次性本地 Claude Code 进程。stdio-live- 在受管理的持久 Claude stdio 会话上的一个轮次。paired-node-cli- 委托给配对节点的一次性 Claude Code 执行。
Claude CLI 诊断仅在进程诊断分发器启用且附加了内部或受信任事件监听器时实例化。当没有可观测性插件或其他监听器处于活动状态时,Claude CLI 轮次会跳过合成 trace 层级、内容缓冲区和诊断流字节核算。当启用内容捕获时,提示和系统提示字段各自上限为 128 KiB;助手输出在最多 200 个信封中上限为 128 KiB,并保留 16 KiB 和一个条目用于最终可见的回退响应。达到限制时,标记会记录截断。
OpenClaw 为 Claude CLI 轮次提供与其他 agent 运行时相同的所有权层级:openclaw.harness.run(openclaw.harness.id = claude-cli)包含 openclaw.run,后者包含 Claude 的 openclaw.model.call span。harness 和 run span 是合成的 OpenClaw 轮次边界,而不是 Claude Code 内部阶段。一次性与受管理 stdio 轮次使用相同层级;真实的新会话重试会在同一 OpenClaw run 内创建另一个模型调用子 span。
span 在 OpenClaw 接受已准备好的 CLI 轮次时开始,并且仅在该轮次成功或失败后结束。对于受管理会话,当 Claude 报告持有结果的后台代理或工作流时,临时成功结果不会结束 span;最终排空后的结果会结束它。中止、超时、进程失败、输出/解析失败以及其他轮次失败会以错误结束同一 span。
Claude Code 报告每条助手消息的用量,并可能在其终端结果上报告累计用量。OpenClaw 回复核算继续使用最后一条助手消息,因此现有成本语义不会改变;轮次级模型调用 span 在可用时使用终端累计用量,包括缓存读取和缓存创建 token。
对于这些 CLI span,字节和计时字段描述可观测的 OpenClaw CLI 边界:
openclaw.model_call.request_bytes是通过一次性 stdin/argv 发送的提示值,或受管理 stdio JSONL 用户信封的 UTF-8 大小。它不是 Claude Code 隐藏模型请求的大小。openclaw.model_call.response_bytes是在轮次期间观察到的 Claude CLI stdout 的 UTF-8 大小。它不是 Anthropic HTTP 响应大小。openclaw.model_call.time_to_first_byte_ms是到第一个可观测 Claude CLI stdout 或 stderr 输出的时间。它不是网络 TTFB。
启用 captureContent 时,span 通过 gen_ai.input.messages 和 gen_ai.output.messages 导出 OpenClaw 发送给 Claude Code 的有效提示以及可见的助手文本/工具调用标识。工具参数、内部思考、不透明思考签名、工具结果和系统提示会从 Claude 助手信封中省略。OpenClaw 不声称可以访问 Claude Code 的私有系统提示、隐藏的恢复或压缩请求负载、原生内部工具模式、原始 Anthropic HTTP 请求、内部重试、上游请求 id 或真实网络 TTFB。由于 Claude Code 未准确暴露其有效原生工具定义,这些 span 不会填充 gen_ai.tool.definitions。
外部 Claude harness 工具 span 即使在启用工具内容捕获时仍仅包含元数据。与每个模型 span 一样,捕获的 Claude CLI 内容使用仅受信任监听器路径以及导出器现有的脱敏和大小边界;内容默认保持关闭。
导出的指标¶
Gateway RPC¶
经过身份验证的 Gateway WebSocket 请求(包括专用 worker RPC)在诊断和感兴趣的导出器启用时发出这些指标。它们排除连接握手、格式错误的请求帧和 HTTP 路由。
| 指标 | 类型 | 测量 |
|---|---|---|
openclaw.gateway.rpc.requests |
counter | 接收到的有效请求,包括随后被拒绝的请求 |
| 指标 | 类型 | 测量 |
|---|---|---|
openclaw.gateway.rpc.first_response_ms |
直方图 | 从接收到首个成功发送的响应 |
openclaw.gateway.rpc.handler_ms |
直方图 | 从实际调用处理程序到返回或抛出异常 |
openclaw.gateway.rpc.admission_ms |
直方图 | 从接收到实际调用处理程序 |
openclaw.gateway.rpc.queue_wait_ms |
直方图 | 适用时,Operator 启动队列或 worker 帧队列等待 |
openclaw.gateway.rpc.outcomes |
计数器 | 按阶段和结果统计的观察值 |
请求和计时指标只有 openclaw.gateway.rpc.method:一个精确的核心、worker 或已注册插件方法名,未注册的通用请求为 other,无法识别的专用 worker RPC 为 unknown。结果指标只有 openclaw.gateway.rpc.phase 和 openclaw.gateway.rpc.outcome,因此错误不会使每个方法的序列倍增。请求、连接、会话或跟踪 ID 不会出现在指标属性中。
Operator 准入包括授权、延迟加载路由器和处理程序,以及启动队列等待。Worker 准入包括 socket FIFO 等待和外层帧验证。Worker 处理程序持续时间包括方法验证和服务调用。Worker 计时从 JavaScript socket 回调开始,排除该回调之前的网络延迟和事件循环延迟。对于会启动的处理程序,队列等待是准入的子集,与命令/会话通道 openclaw.queue.wait_ms 分开。处理程序和准入样本仅存在于被调用的处理程序中。队列等待在调度结算时记录。
Worker 推理开始计时衡量接收和初始化,而非提供商完成。长时间的 worker 计算机和会话操作在释放 socket FIFO 后仍保留其处理程序计时。Worker 调度结果描述返回或抛出异常。连接关闭可能在成功执行后抑制响应,并且本身不能证明执行已取消。
已发送响应表示 WebSocket 发送方接受了帧,而不是客户端已收到它。早期确认计为首个响应;后续响应不会增加另一个样本。不可用或被抑制的发送会贡献结果,但不贡献首个响应样本。处理程序可能在保留的回调发送其响应之前返回,并且分离的 agent 工作之后可以继续。这些持续时间测量经过时间,包括异步等待,而不是 CPU 时间或事件循环阻塞时间。
观察值使用有界诊断队列。在饱和期间将计数或延迟分布视为完整之前,请检查 openclaw.diagnostic.async_queue.dropped。
模型使用¶
openclaw.tokens(计数器,属性:openclaw.token、openclaw.channel、openclaw.provider、openclaw.model、openclaw.agent)openclaw.cost.usd(计数器,属性:openclaw.channel、openclaw.provider、openclaw.model)openclaw.run.duration_ms(直方图,属性:openclaw.channel、openclaw.provider、openclaw.model)openclaw.context.tokens(直方图,属性:openclaw.context、openclaw.channel、openclaw.provider、openclaw.model)gen_ai.client.token.usage(直方图,GenAI 语义约定指标,属性:gen_ai.token.type=input/output、gen_ai.provider.name、gen_ai.operation.name、gen_ai.request.model)gen_ai.client.operation.duration(直方图,秒,用于模型请求和合成 agent 轮次的 GenAI 语义约定指标;属性:gen_ai.provider.name、gen_ai.operation.name、gen_ai.request.model、可选error.type;轮次观察值使用gen_ai.operation.name = invoke_agent)openclaw.model_call.duration_ms(直方图,属性:openclaw.provider、openclaw.model、openclaw.api、openclaw.transport、openclaw.model_call.observation_unit,以及在已分类错误上的openclaw.errorCategory和openclaw.failureKind)openclaw.model_call.request_bytes(直方图,最终模型请求负载的 UTF-8 字节大小;对于 Claude Code CLI,为上文描述的可见提示输入/信封;不包含原始负载内容)openclaw.model_call.response_bytes(直方图,流式响应块负载的 UTF-8 字节大小;高频文本、思考和工具调用增量仅统计增量delta字节;对于 Claude Code CLI,为观察到的 stdout 字节;不包含原始响应内容)openclaw.model_call.time_to_first_byte_ms(直方图,首个流式响应事件之前的经过时间;对于 Claude Code CLI,为首个可观察的 CLI 输出,而非网络 TTFB)openclaw.model.failover(计数器,属性:openclaw.provider、openclaw.model、openclaw.failover.to_provider、openclaw.failover.to_model、openclaw.failover.reason、openclaw.failover.suspended、openclaw.lane)openclaw.skill.used(计数器,属性:openclaw.skill.name、openclaw.skill.source、openclaw.skill.activation、可选openclaw.agent、可选openclaw.toolName)
消息流¶
openclaw.webhook.received(计数器,属性:openclaw.channel、openclaw.webhook)openclaw.webhook.error(计数器,属性:openclaw.channel、openclaw.webhook)openclaw.webhook.duration_ms(直方图,属性:openclaw.channel、openclaw.webhook)openclaw.message.queued(计数器,属性:openclaw.channel、openclaw.source)openclaw.message.received(计数器,属性:openclaw.channel、openclaw.source)openclaw.message.dispatch.started(计数器,属性:openclaw.channel、openclaw.source)openclaw.message.dispatch.completed(计数器,属性:openclaw.channel、openclaw.outcome、openclaw.reason、openclaw.source)openclaw.message.dispatch.duration_ms(直方图,属性:openclaw.channel、openclaw.outcome、openclaw.reason、openclaw.source)openclaw.message.processed(计数器,属性:openclaw.channel、openclaw.outcome)openclaw.message.duration_ms(直方图,属性:openclaw.channel、openclaw.outcome)openclaw.message.delivery.started(计数器,属性:openclaw.channel、openclaw.delivery.kind)openclaw.message.delivery.duration_ms(直方图,属性:openclaw.channel、openclaw.delivery.kind、openclaw.outcome、openclaw.errorCategory)
对话¶
openclaw.talk.event(计数器,属性:openclaw.talk.event_type、openclaw.talk.mode、openclaw.talk.transport、openclaw.talk.brain、openclaw.talk.provider)openclaw.talk.event.duration_ms(直方图,属性:与openclaw.talk.event相同;当对话事件报告持续时间时发出)openclaw.talk.audio.bytes(直方图,属性:与openclaw.talk.event相同;为报告字节长度的对话音频帧事件发出)
队列与会话¶
openclaw.queue.lane.enqueue(计数器,属性:openclaw.lane)openclaw.queue.lane.dequeue(计数器,属性:openclaw.lane)openclaw.queue.depth(直方图,属性:openclaw.lane或openclaw.channel=heartbeat)openclaw.queue.wait_ms(直方图,属性:openclaw.lane)openclaw.session.state(计数器,属性:openclaw.state、openclaw.reason)openclaw.session.stuck(计数器,属性:openclaw.state;为可恢复的陈旧会话簿记发出)openclaw.session.stuck_age_ms(直方图,属性:openclaw.state;为可恢复的陈旧会话簿记发出)openclaw.session.turn.created(计数器,属性:openclaw.agent、openclaw.channel、openclaw.trigger)openclaw.session.recovery.requested(计数器,属性:openclaw.state、openclaw.action、openclaw.active_work_kind、openclaw.reason)openclaw.session.recovery.completed(计数器,属性:openclaw.state、openclaw.action、openclaw.status、openclaw.active_work_kind、openclaw.reason)openclaw.session.recovery.age_ms(直方图,属性:与对应的恢复计数器相同)openclaw.run.attempt(计数器,属性:openclaw.attempt)
会话存活遥测¶
当 OpenClaw 观察到回复、工具、状态、块或 ACP 运行时进展时,processing 会话不会朝着内置存活阈值老化。输入保活不计为进展,因此仍可检测到静默的模型或 harness。
OpenClaw 根据仍可观察到的工作对会话进行分类:
session.long_running:活动的嵌入式工作、模型调用或工具调用仍在取得进展。在内置中止阈值之前,有归属的静默模型调用也会报告为长时间运行,因此缓慢或非流式模型提供程序不会在中止可观察期间看起来像停滞的网关会话。session.stalled:存在活动工作,但活动运行未报告近期进展。有归属的模型调用在达到或超过内置中止阈值后,会从session.long_running切换为session.stalled;无归属的陈旧模型/工具活动不会被视为无害的长时间运行工作。停滞的嵌入式运行最初保持仅观察状态,然后在中止阈值后若无进展则中止排空,以便该通道后面排队的轮次可以恢复。session.stuck:没有活动工作的陈旧会话簿记,或带有陈旧无归属模型/工具活动的空闲排队会话。在恢复门控通过后,这会立即释放受影响的会话通道。
恢复会发出结构化的 session.recovery.requested 和 session.recovery.completed 事件。诊断会话状态只有在发生变更型恢复结果(aborted 或 released)之后,并且仅当同一处理代仍为当前时,才会被标记为空闲。
只有 session.stuck 会发出 openclaw.session.stuck 计数器、openclaw.session.stuck_age_ms 直方图和 openclaw.session.stuck span。当会话保持不变时,重复的 session.stuck 诊断会退避,因此仪表盘应针对持续增加告警,而不是每个心跳 tick。有关配置项和默认值,请参阅配置参考。
存活告警还会发出:
openclaw.liveness.warning(计数器,属性:openclaw.liveness.reason)openclaw.liveness.event_loop_delay_p99_ms(直方图,属性:openclaw.liveness.reason)openclaw.liveness.event_loop_delay_max_ms(直方图,属性:openclaw.liveness.reason)openclaw.liveness.event_loop_utilization(直方图,属性:openclaw.liveness.reason)openclaw.liveness.cpu_core_ratio(直方图,属性:openclaw.liveness.reason)
CPU 比率以核心当量衡量整个进程的 CPU 使用率,包括工作线程和原生线程,并且可能超过 1。事件循环延迟和利用率单独衡量主线程。请参阅CPU 压力和事件循环延迟。
网关事件循环观察窗口¶
openclaw.gateway.event_loop.delay_max_ms(直方图,无属性;每个已完成健康监控窗口的最大延迟)openclaw.gateway.event_loop.observed_ms(计数器,无属性;已完成窗口所代表的经过毫秒数)
这些指标使用现有的诊断插件配置,并且要求指标处于活动状态。每个被接受的健康监控窗口只记录一次,因此后来的健康就绪结果不会抹去先前的高延迟观察。健康检查和抓取读取不会提交或重置样本。进程级观察不携带请求跟踪上下文,也不会创建 span 或日志,即使使用预加载的 SDK 也是如此。
监控器每 20 毫秒采样一次经过的事件循环间隔,并在至少一秒后完成窗口;对于延迟告警,可能会更早完成。普通窗口重置会保留待处理间隔,即使健康读取发生在逾期样本之前也是如此。计数和分位数描述的是已完成窗口及其最大值,而不是单个停滞或采样延迟分布的总体 p99。有意重置监控器会丢弃未完成的窗口;采集不会为没有感兴趣导出器的时间段回填数据。诊断队列丢弃、SDK/导出失败和重启会限制覆盖范围。请使用所代表时长计数器和导出器/丢弃遥测来评估它。就绪决策和持久存活告警阈值保持不变。有关拉取指标和示例查询,请参阅Prometheus 事件循环窗口。
Harness 生命周期¶
openclaw.harness.duration_ms(直方图,属性:openclaw.harness.id、openclaw.harness.plugin、openclaw.outcome,出错时还有openclaw.harness.phase)
工具执行与循环检测¶
openclaw.tool.execution.duration_ms(直方图,属性:gen_ai.tool.name、openclaw.toolName、openclaw.tool.source、openclaw.tool.owner、openclaw.tool.params.kind,错误时附加openclaw.errorCategory)openclaw.tool.execution.blocked(计数器,属性:gen_ai.tool.name、openclaw.toolName、openclaw.tool.source、openclaw.tool.owner、openclaw.tool.params.kind、openclaw.deniedReason)openclaw.tool.loop(计数器,属性:openclaw.toolName、openclaw.loop.level、openclaw.loop.action、openclaw.loop.detector、openclaw.loop.count,可选openclaw.loop.paired_tool;在检测到重复工具调用循环时发出)
执行¶
openclaw.exec.duration_ms(直方图,属性:openclaw.exec.target、openclaw.exec.mode、openclaw.outcome、openclaw.failureKind)
诊断内部(内存、负载、导出器健康)¶
openclaw.gc.duration_ms(直方图,无属性;宿主 JavaScript isolate 的 GC 持续时间)
GC 持续时间使用 Node.js performance entries,并且仅在启用指标时导出。它不是 CPU 时间,也不是保证的全局暂停。观察在现有诊断心跳发现感兴趣的消费者时开始;启动后的注册可以等待到其下一个 30 秒 tick,且不会回填。禁用/关闭诊断会立即断开连接。参见 GC 持续时间覆盖范围与关联限制。
openclaw.payload.large(计数器,属性:openclaw.payload.surface、openclaw.payload.action、openclaw.channel、openclaw.plugin、openclaw.reason)openclaw.payload.large_bytes(直方图,属性:与openclaw.payload.large相同)openclaw.memory.rss_bytes/openclaw.memory.heap_used_bytes/openclaw.memory.heap_total_bytes/openclaw.memory.external_bytes/openclaw.memory.array_buffers_bytes(直方图,无属性;进程内存采样)openclaw.memory.pressure(计数器,属性:openclaw.memory.level、openclaw.memory.reason)openclaw.diagnostic.async_queue.dropped(计数器,属性:openclaw.diagnostic.async_queue.drop_class;内部诊断队列背压丢弃)openclaw.telemetry.exporter.events(计数器,属性:openclaw.exporter、openclaw.signal、openclaw.status,可选openclaw.reason,可选openclaw.errorCategory;导出器生命周期/失败自遥测)
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw