监控与分析

Claude Code 有两类观测能力:本地/企业可配置的 OpenTelemetry 导出,以及 Anthropic 组织侧的 analytics dashboard。它们解决的问题不同。

#OpenTelemetry 快速开始

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

claude

调试时可以缩短导出周期:

export OTEL_METRIC_EXPORT_INTERVAL=10000
export OTEL_LOGS_EXPORT_INTERVAL=5000

生产环境不要把 interval 设得太短,否则观测系统和本机都会增加负担。

#管理员下发

组织可以通过 managed settings 强制启用:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

Managed settings 里的环境变量优先级高,普通用户不能覆盖。注意 Claude Code 不会把 OTEL_* 自动传给 Bash、Hooks、MCP servers 或 language servers。如果这些子进程也要导出 telemetry,需要单独配置。

#常用环境变量

#Metrics cardinality

高基数字段会让监控存储变贵。官方提供这些开关:

团队维度可以用:

export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

不要在这里放空格或高基数随机值。

#Traces

Tracing 需要额外打开 beta 开关:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp

每个用户 prompt 会形成 claude_code.interaction root span,下面挂 API 请求、工具调用和 Hook 执行。子代理的 API 和工具 span 会挂在父级 Agent tool span 下。

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── subagent claude_code.llm_request / claude_code.tool

当 tracing 打开时,Bash 和 PowerShell 子进程会收到 TRACEPARENT。如果你通过自定义 ANTHROPIC_BASE_URL 代理模型请求,默认不会把 traceparent 发给第三方 provider。确实要传播时设置:

export CLAUDE_CODE_PROPAGATE_TRACEPARENT=1

#Analytics dashboard

Team/Enterprise 的贡献指标需要 GitHub app 和组织设置。它会统计 Claude Code 辅助的 PR、代码行、接受率和活跃用户。Zero Data Retention 组织只能看 usage metrics,不能看贡献指标。

API 用户的 Console dashboard 主要显示 accepted lines、suggestion accept rate、activity、spend 和 per-user insights。Spend 是 analytics 估算,实际账单以 billing 为准。

#和缓存、成本的关系

如果要优化 Passion8 账单,优先看 Prompt 缓存、成本优化 和 Passion8 控制台,不要只看 Anthropic dashboard。

#官方参考

• Monitoring with OpenTelemetry
• Track team usage with analytics
• Status line
• Manage costs effectively