openclaw-apm-tracing

v0.5.3

Published

a month ago

OpenClaw APM tracing plugin — full-chain distributed tracing with parent-child span tree. Requires diagnostics-otel for OTel SDK export.

0High
0Medium
0Low

klauslin

openclaw openclaw-plugin opentelemetry apm observability tracing llm

openclaw-apm-tracing

OpenClaw APM 链路追踪插件（2026.6.5+ beta）—— 通过 lifecycle hooks 构建 parent-child span 树，配合 diagnostics-otel 导出到任意 OTLP 后端。

npm 包名：openclaw-apm-tracing（beta）
插件 ID：openclaw-apm-tracing

功能

自动追踪：Hook 19 个 OpenClaw 生命周期事件，自动生成完整的链路追踪
Span 树结构：openclaw.message → openclaw.session → openclaw.agent → chat {model} / openclaw.tool.{name} 等
APM 兼容：支持 GenAI / Traceloop 语义，适配常见 APM LLM Tab
智能截断：自动截断超长 span 属性，保证 JSON 合法性（阈值可配，见下）

截断阈值配置

超长文本（如 system prompt、entity input/output）默认截断到 65536 字符，避免超大 span attribute 被 APM/OTel 后端丢弃。排查问题需要完整内容时，可通过环境变量调整（无需改代码/重新发版）：

# 调大阈值
OPENCLAW_APM_MAX_CONTENT_LENGTH=131072

# 完全关闭截断（0 / -1 / off 均可）
OPENCLAW_APM_MAX_CONTENT_LENGTH=0

⚠️ 关闭截断仅建议用于临时排查：APM/OTel 后端对单个 attribute value 长度通常有上限，超限可能导致整条 span 被丢弃。

前置条件

OpenClaw 版本 ≥ 2026.6.5
已安装并启用 @openclaw/diagnostics-otel 插件（负责注册全局 OTel SDK 并导出到 OTLP 端点）
已在 diagnostics.otel 中配置 OTLP endpoint（可对接任意兼容后端，包括腾讯云 APM）

关于 diagnostics-otel：从 OpenClaw 2026.5+ 起独立为 npm 包 @openclaw/diagnostics-otel，插件 ID 仍为 diagnostics-otel。本插件通过 @opentelemetry/api 挂载到 diagnostics-otel 注册的全局 TracerProvider，无需代码级耦合。

安装

openclaw plugins install openclaw-apm-tracing@beta
openclaw plugins install @openclaw/diagnostics-otel

若曾安装过旧包名，先卸载：

openclaw plugins uninstall openclaw-tencent-plugin
openclaw plugins uninstall openclaw-apm-tracing
openclaw plugins install openclaw-apm-tracing@beta

启用插件

编辑 ~/.openclaw/openclaw.json：

重要（OpenClaw 2026.6+）：本插件订阅了 llm_input / llm_output / before_model_resolve / agent_end 等 conversation hooks，必须配置 allowConversationAccess。

{
  "plugins": {
    "allow": ["diagnostics-otel", "openclaw-apm-tracing"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      },
      "openclaw-apm-tracing": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://your-otlp-endpoint:90/otlp",
      "protocol": "http/protobuf",
      "headers": {
        "Authorization": "<YOUR_OTLP_TOKEN>"
      },
      "serviceName": "openclaw",
      "traces": true,
      "metrics": true
    }
  }
}

重启并验证

openclaw gateway restart
openclaw plugins list
openclaw plugins inspect openclaw-apm-tracing --runtime

启动后日志中应出现：

[openclaw-apm-tracing] Plugin registered (service mode)
[openclaw-apm-tracing] Typed hooks registered during plugin register(): count=19
[openclaw-apm-tracing] Attaching to global TracerProvider (api=/path/to/shared/@opentelemetry/api)
[openclaw-apm-tracing] TracerProvider probe OK: traceId=<32-hex> spanId=<16-hex>
[openclaw-apm-tracing] Service started (hooksRegistered=19, activeStates=0, tracerLive=true)

收到消息后应出现（示例）：

[openclaw-apm-tracing] [message_received] key=xxx:...
[openclaw-apm-tracing] Started root span: traceId=<32-hex> ... parentSource=active-context inboundTraceId=<backend-trace-id>
[openclaw-apm-tracing] [before_agent_start] ...
[openclaw-apm-tracing] [llm_input] ...

parentSource 含义：

| 值 | 说明 | |----|------| | hook.trace / hook.traceId | 外部 channel 通过 OpenClaw hook 传入 trace | | traceparent | W3C traceparent 传播 | | active-context | 继承当前 OTel active span（如元宝 pipeline.execute） | | new-trace | 无外部 trace，本地新建 |

客户侧用后端日志 traceId 查 APM 时，应看到 parentSource=active-context 或 hook.traceId，且 root span 的 traceId 与后端一致。

开发

npm install
npm run build

发布 beta（npm 公网 registry.npmjs.org）：

npm login   # 首次需登录
npm run publish:beta

云服务器安装（无需 git，默认从 npmjs 拉取）：

openclaw plugins install openclaw-apm-tracing@beta

版本

v0.5.3 — 正式发布：修复 LLM 本轮回答缺失（message_sent 抢跑、智研只渲染 input JSON）；超过 10 条 prompt 时索引补零避免乱序
v0.5.3-beta.2 — 本轮回答追加进 traceloop.entity.input（智研模型交互信息只渲染 input JSON）；llm_output 抽不到文本时不关 span，从 message_sending / agent_end 回填
v0.5.3-beta.1 — 修复 LLM span 本轮回答缺失（message_sent 抢跑 / 工具轮次无 llm_output）；超过 10 条 prompt 时索引补零，避免 APM 按字符串排序乱序
v0.5.2 — 正式发布：跨插件 inbound trace 通道作为最高优先级传播源（内容同 v0.5.1）
v0.5.1 — 新增跨插件 inbound trace 通道作为最高优先级传播源，直接消费 channel 插件发布的后端 traceId，不依赖 OTel 注册时序；before_prompt_build / before_agent_start 的 fallback 路径改为复用同一套父级解析而非 ROOT_CONTEXT
v0.5.0-beta.6 — message_received 支持外部 trace 传播：优先 hook traceId / traceparent，其次继承 OTel active context（与 channel 后端 traceId 对齐）；日志输出 parentSource
v0.5.0-beta.5 — 修复 host api 解析：优先从 peer-linked openclaw 与 sibling diagnostics-otel 查找；恢复 bundled fallback 避免插件加载失败
v0.5.0-beta.4 — 修复 @opentelemetry/api 多实例导致 traceId 全 0 / 链路不导出；启动时 TracerProvider probe + 解析路径日志
v0.5.0-beta.3 — 将 typed hook 注册从 service.start() 移到 register()，修复运行时 hook 不触发；增加注册计数日志
v0.5.0-beta.2 — 去掉 scope，npm 包名 openclaw-apm-tracing
v0.5.0-beta.1 — scoped 包 @klauslin/openclaw-apm-tracing / 插件 ID openclaw-apm-tracing
v0.5.0-beta.0 — 初版 beta（旧名 @klauslin/openclaw-tencent-plugin）
v0.4.0 — 上游初始版本（仅 TS 源码，不兼容 2026.6+ install）

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

openclaw-apm-tracing

功能

截断阈值配置

前置条件

安装

启用插件

重启并验证

开发

版本