跳转至

Spans 和事件

导出的 span

  • openclaw.gateway.rpc.response、openclaw.gateway.rpc.handler、openclaw.gateway.rpc.dispatch
  • 包含 openclaw.gateway.rpc.method、openclaw.gateway.rpc.phase 和 openclaw.gateway.rpc.outcome 的已完成阶段观测
  • handler span 包含 openclaw.gateway.rpc.admission_ms；dispatch span 包含 openclaw.gateway.rpc.response，即 dispatch 结算时的响应状态

  • 保留提供的上游请求父级；它们不会引入长期存在的 RPC 父级 span，也不会改变下游 trace 传播

  • openclaw.model.usage

  • openclaw.channel、openclaw.provider、openclaw.model、可选 openclaw.agent（已知时拥有该 run 的 agent）
  • 可选的主机派生 openclaw.plugin，仅用于受信任插件运行时完成
  • openclaw.tokens.*（input/output/cache_read/cache_write/total）
  • 默认 gen_ai.system，或在启用最新 GenAI 语义约定时使用 gen_ai.provider.name
  • gen_ai.request.model、gen_ai.operation.name、gen_ai.usage.*

插件归属仅针对 span。它不会为共享的 OpenTelemetry 指标添加插件维度，也不会更改 Prometheus 指标标签。

  • openclaw.run
  • openclaw.outcome、openclaw.channel、openclaw.provider、openclaw.model、openclaw.errorCategory、可选 openclaw.agent
  • openclaw.model.call
  • 默认 gen_ai.system，或在启用最新 GenAI 语义约定时使用 gen_ai.provider.name
  • gen_ai.request.model、gen_ai.operation.name、openclaw.provider、openclaw.model、openclaw.api、openclaw.transport、openclaw.model_call.observation_unit（request 或 turn）、可选 openclaw.agent
  • 错误时的 openclaw.errorCategory、error.type 和可选 openclaw.failureKind
  • openclaw.model_call.request_bytes、openclaw.model_call.response_bytes、openclaw.model_call.time_to_first_byte_ms
  • openclaw.model_call.prompt.input_messages_count、openclaw.model_call.prompt.input_messages_chars、openclaw.model_call.prompt.system_prompt_chars、openclaw.model_call.prompt.tool_definitions_count、openclaw.model_call.prompt.tool_definitions_chars、openclaw.model_call.prompt.total_chars（仅包含安全的组件大小，不包含 Prompt 文本）
  • 当结果携带该 request 或聚合 turn 的 usage 时，包含 openclaw.model_call.usage.* 和 gen_ai.usage.*
  • 当上游 provider 结果暴露 request id 时，span 事件 openclaw.provider.request 带有属性 openclaw.upstreamRequestIdHash（有界、基于哈希）；原始 id 永远不会导出
  • 当设置 OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental 时，request span 使用最新的 GenAI 推理 span 名称 {gen_ai.operation.name} {gen_ai.request.model}。Turn span 使用 invoke_agent，因为 OpenClaw 不会从不透明的 CLI 边界声明原生 agent 名称。两者都使用 CLIENT span 类型，而不是 openclaw.model.call。
  • openclaw.harness.run
  • openclaw.harness.id、openclaw.harness.plugin、openclaw.outcome、openclaw.provider、openclaw.model、openclaw.channel、可选 openclaw.agent
  • 完成时：openclaw.harness.result_classification、openclaw.harness.yield_detected、openclaw.harness.items.started、openclaw.harness.items.completed、openclaw.harness.items.active
  • 错误时：openclaw.harness.phase、openclaw.errorCategory、可选 openclaw.harness.cleanup_failed
  • span 事件 openclaw.agent.commentary 用于受支持 harness 的已完成前言，包括内置运行时、Codex 和 Claude CLI。属性包括 openclaw.commentary.sequence、openclaw.commentary.text_length 和 openclaw.commentary.content_truncated。现有的 diagnostics.otel.captureContent 设置控制有界、脱敏的输出消息内容。
  • openclaw.tool.execution
  • gen_ai.tool.name、gen_ai.operation.name（execute_tool）、openclaw.toolName、openclaw.tool.source、可选 gen_ai.tool.call.id、openclaw.tool.owner、openclaw.tool.params.*、可选 openclaw.agent
  • 错误时可选 openclaw.errorCategory/openclaw.errorCode，当被策略或沙箱拒绝时包含 openclaw.deniedReason 和 openclaw.outcome=blocked
  • openclaw.exec
  • openclaw.exec.target、openclaw.exec.mode、openclaw.outcome、openclaw.failureKind、openclaw.exec.command_length、openclaw.exec.exit_code、openclaw.exec.exit_signal、openclaw.exec.timed_out
  • openclaw.webhook.processed
  • openclaw.channel、openclaw.webhook
  • openclaw.webhook.error
  • openclaw.channel、openclaw.webhook、openclaw.error
  • openclaw.message.processed
  • openclaw.channel、openclaw.outcome、openclaw.reason、可选 openclaw.agent（最初摄取该 Prompt 的 agent）
  • 隔离的 cron agent turn 将此 span 作为其 harness span 的父级，使模型调用、工具和 usage 在成功完成或失败期间都保持在同一 trace 中。
  • openclaw.message.delivery
  • openclaw.channel、openclaw.delivery.kind、openclaw.outcome、openclaw.errorCategory、openclaw.delivery.result_count
  • openclaw.session.stuck
  • openclaw.state、openclaw.ageMs、openclaw.queueDepth
  • openclaw.context.assembled
  • openclaw.prompt.size、openclaw.history.size、openclaw.context.tokens、openclaw.errorCategory（不包含 Prompt、历史、响应或会话密钥内容）
  • openclaw.tool.loop
  • openclaw.toolName、openclaw.loop.level、openclaw.loop.action、openclaw.loop.detector、openclaw.loop.count、可选 openclaw.loop.paired_tool、可选 openclaw.agent（不包含循环消息、参数或工具输出）
  • openclaw.memory.pressure
  • openclaw.memory.level、openclaw.memory.reason、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.threshold_bytes/openclaw.memory.rss_growth_bytes/openclaw.memory.window_ms

当明确启用内容捕获时，模型和工具 span 还可以包含有界、脱敏的 openclaw.content.* 属性，用于你选择启用的特定内容类别。

诊断事件目录

以下事件支撑上述 指标 和 span。公开事件也可 用于直接插件订阅；受信任的核心事件（如 model.usage）仅限授权内部消费者使用。 run.progress 和 run.execution_phase 是仅限直接使用的生命周期信号； diagnostics-otel 插件不会将它们作为独立 OTLP 信号导出。 事件类型和 run.execution_phase.phase 值是可增量扩展的。TypeScript 消费者应保留默认分支，而不是假定任一联合类型 永远穷尽。

agent.commentary 记录已完成的前言，而不是文本增量。它携带 原始 agent 事件序列和时间戳，并附加到活动 harness span。最近重复的完成事件会按尝试抑制。与其他 排队诊断一样，commentary 在队列压力下可能被丢弃；会话 记录仍是持久的对话记录。在 debug 级别， diagnostic 日志记录器还会记录完成元数据，但不包含 commentary 文本。

模型用量

model.usage 是受信任的进程内诊断事件，而不是 JSONL 日志 记录。一个代表性事件具有如下结构：

{
  "type": "model.usage",
  "ts": 1735689600000,
  "seq": 42,
  "provider": "openai",
  "model": "gpt-5.4",
  "channel": "webchat",
  "agentId": "main",
  "sessionId": "session-123",
  "sessionKey": "agent:main:main",
  "usage": {
    "input": 120,
    "output": 40,
    "cacheRead": 30,
    "cacheWrite": 10,
    "promptTokens": 160,
    "total": 200
  },
  "lastCallUsage": {
    "input": 120,
    "output": 40,
    "cacheRead": 30,
    "cacheWrite": 10,
    "total": 200
  },
  "context": { "limit": 128000, "used": 160 },
  "costUsd": 0.0012,
  "durationMs": 850,
  "trace": {
    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "spanId": "00f067aa0ba902b7",
    "traceFlags": "01"
  }
}
  • ts 是毫秒级 Unix 时间戳；seq 是进程本地的。
  • usage 保存轮次级 token 计数。promptTokens 包含 input、 cacheRead 和 cacheWrite；lastCallUsage（如果可用）描述 最后一次模型调用。
  • context.used 是当前 prompt/context 快照，当涉及缓存输入或工具循环调用时， 可能低于 usage.total。
  • 提供商/模型/会话标识符、token 桶、lastCallUsage、 context、costUsd、durationMs 和 trace 字段是可选的。 costUsd 是估算值，当模型定价不可用时可能缺失； 它不是提供商报告的账单。Trace 上下文还可以包含 parentSpanId。

网关的 /tmp/openclaw/openclaw-YYYY-MM-DD.log JSONL 文件和 diagnostics.otel.logsExporter: "stdout" 包含普通日志记录，而不是原始 model.usage 事件。公开诊断订阅和 diagnostics.stability 不暴露受信任的核心用量事件。 diagnostics-otel 插件会将它们转换为指标（如 openclaw.tokens 和 openclaw.cost.usd）以及 openclaw.model.usage span；这些用量指标 和 span 有意省略会话标识符。

对于需要会话关联用量的外部集成，请改为查询 已认证的网关：

openclaw gateway call sessions.usage --params '{"range":"30d","agentScope":"all"}' --json
openclaw gateway usage-cost --days 30 --all-agents --json

两个命令都需要 operator.read。sessions.usage 可以包含按会话的 sessionId、提供商/模型详情以及 token/成本摘要；按会话的用量 在其缓存刷新期间可能暂时为 null。usage-cost 提供 聚合估算。省略 agentScope 或 --all-agents 可将报告范围 限定为默认 agent。对于持续更新的客户端， 改为订阅会话变更而不是轮询用量报告。 参见 Gateway RPC 方法参考 了解用量方法和请求选项。

消息流

  • webhook.received / webhook.processed / webhook.error
  • message.queued / message.processed
  • message.delivery.started / message.delivery.completed / message.delivery.error

Gateway RPC

  • gateway.rpc - 受信任的请求观测，阶段为 received、response、 handler 和 dispatch。响应结果为 ok、error、unavailable 或 suppressed；handler 结果为 returned 或 threw；dispatch 结果 为 returned、threw、rejected 或 cancelled。Dispatch 在结算时记录其响应 状态（none、sent、unavailable 或 suppressed）；稍后的 响应仍可能到达。时长和队列/准入语义在 Gateway RPC 指标 中描述。

队列与会话

  • queue.lane.enqueue / queue.lane.dequeue
  • session.state / session.long_running / session.stalled / session.stuck
  • run.attempt / run.progress
  • run.execution_phase（公开，会话关联的嵌入式 runner 启动里程碑）
  • diagnostic.heartbeat（聚合计数器：webhooks/queue/session）
  • gateway.event_loop.sample（内部仅指标的已完成窗口：intervalMs、delayMaxMs；无 reader 身份）

Harness 生命周期

  • harness.run.started / harness.run.completed / harness.run.error - agent harness 的每次运行生命周期。包含 harnessId、可选 pluginId、提供商/模型/通道和 run id。完成时添加 durationMs、outcome、可选 resultClassification、yieldDetected 和 itemLifecycle 计数。错误添加 phase （prepare/start/send/resolve/cleanup）、errorCategory 和 可选 cleanupFailed。

执行

  • exec.process.completed - 终止结果、时长、目标、模式、退出 代码和失败类型。不包含命令文本和工作目录。
  • exec.approval.followup_suppressed - 会话重新绑定后丢弃的过期审批后续。包含 approvalId、reason （session_rebound）、phase（direct_delivery 或 gateway_preflight） 以及 dispatcher 时间戳。不包含会话键、路由和命令文本。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw