TLS Observer for Claude Code

将 Claude Code 的 prompt、assistant response、tool call、token usage、subagent 和 compact 事件转换为 GenAI Trace，并通过 Volcengine TLS Producer 写入 Trace Topic。

安装

推荐使用安装器：

npm exec -y \
  --package=@volcengine/tls-observer-claude-code-install -- \
  tls-observer-claude-code-install

安装器会：

1. 从 registry 下载插件包。
2. 安装到 ~/.claude/skills/tls-observer-claude-code。
3. 在 ~/.claude/settings.json 启用 tls-observer-claude-code@skills-dir。
4. 将 TLS 配置写入 ~/.claude/tls-observer-claude-code.env。

采集事件

• UserPromptSubmit
• PreToolUse
• PostToolUse / PostToolUseFailure
• Stop / StopFailure
• SubagentStop
• PreCompact / PostCompact
• SessionEnd

Stop 和 SessionEnd 从 transcript 增量读取当前 turn。工具 hooks 补充工具开始时间、结果和错误状态；Subagent transcript 在主 turn 结束时导出。

Trace

agent.turn (server)
  llm.request (client)
  tool.call (client)

根 span 包含最终模型、prompt、最终 assistant output 和所有模型调用 token 汇总。工具 span 包含：

• gen_ai.tool.name
• gen_ai.tool.call.id
• gen_ai.tool.call.arguments
• gen_ai.tool.call.result
• tool.error
• error.message

所有 span 都包含 session.id 和 tls.app.type=claude-code。对象和数组类 attribute 会 JSON stringify 后写入。

内容采集

插件默认采集完整 prompt、assistant output、tool input/output：

CLAUDE_CODE_TLS_CAPTURE_CONTENT=1

设置为 0 可关闭正文，只保留结构、模型、token 和工具元数据。

本地诊断

默认 data root：

~/.claude/plugins/data/tls-observer-claude-code

最近一次导出结果：

cat ~/.claude/plugins/data/tls-observer-claude-code/logs/send/latest.send-log.json

设置 CLAUDE_CODE_TLS_DEBUG_ARTIFACTS=1 后还会生成：

artifacts/otel-traces/
artifacts/otlp-payloads/
artifacts/schema-aligned/

开发

emo run test --filter @volcengine/tls-observer-claude-code --skip-cache

Rslib 会把 shared OTEL、storage 和 utils 源码内联进 dist/index.js。发布包只携带 dist、hooks、.claude-plugin 和 README。