使用OpenTelemetry实现Claude Code的可观测性
内容提要
本文介绍如何通过可观测性监控Claude Code等智能编码工具的使用成本。文章详细说明了启用Claude Code内置遥测功能、配置OpenTelemetry Collector收集数据，并使用Prometheus、Loki、Jaeger和Grafana等工具分析指标、日志和追踪信息的方法，帮助团队有效追踪和优化AI编码工具的使用费用。
延伸解读
遥测数据的三类信号与用途
文章将遥测数据分为指标、日志和追踪三类。指标适合回答“花了多少钱”“用了多少token”这类聚合问题；日志适合查看单个事件细节，如上下文压缩；追踪则展示一次请求如何拆分为子代理和模型调用。理解三者差异有助于按需选择查询工具，避免用日志做聚合或用指标排查单次事件。
成本估算与订阅费用的差异
文中指出，claude_code_cost_usage_USD_total是基于token数量和官方单价计算的客户端估算值，可能超过订阅费用。对于按API调用付费的团队，该指标更关键；而订阅用户有使用额度但速率受限。因此，在解读成本数据时，需结合自身计费模式，避免误判实际支出。
缓存读取token占比高但成本低
在token类型中，cacheRead（缓存读取）在长会话中占主导，但单价最低；cacheCreation（缓存创建）成本较高。文章示例中，一次约100万token的消耗中，cacheRead占92%。优化提示词以增加缓存命中，可有效降低成本，但需注意缓存创建的开销。
追踪中的隐私与归因局限
追踪数据默认对用户提示词进行脱敏，但设置OTEL_LOG_USER_PROMPTS=1会记录原始提示词，在多用户环境中可能泄露敏感信息。此外，当前追踪无法将子代理调用关联到具体任务或技能，归因能力有限。启用增强遥测时需权衡隐私与可观测性。
Q&A
如何启用Claude Code的内置遥测功能？
可以通过两种方式启用：一是设置环境变量，如CLAUDE_CODE_ENABLE_TELEMETRY=1、CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1，并配置OTEL_METRICS_EXPORTER、OTEL_LOGS_EXPORTER、OTEL_TRACES_EXPORTER为otlp，以及OTEL_EXPORTER_OTLP_ENDPOINT等；二是在~/.claude/settings.json的env字段中设置相同的变量，这样只对Claude Code生效。
Claude Code的遥测数据包含哪些类型？
遥测数据包含三类：指标（Metrics）是数值测量，如总成本、令牌数；日志（Logs）是单个事件的详细记录，如上下文压缩事件；追踪（Traces）是请求的路径，如一次交互中多个子代理的调用。
为什么需要OpenTelemetry Collector？
Collector可以统一接收Claude Code通过OTLP发送的遥测数据，然后分别转发给不同的后端（如Jaeger、Loki、Prometheus），简化配置；它还支持数据缓冲、转换和扇出，在企业网络中只需出站连接，适合生产环境。
如何查看Claude Code的总花费和令牌使用量？
在Prometheus中查询claude_code_cost_usage_USD_total和claude_code_token_usage_tokens_total指标，使用increase()函数计算窗口内的增量，例如sum(increase(claude_code_cost_usage_USD_total[10m]))。也可以在Grafana中配置面板展示。
Claude Code的令牌类型有哪些？哪种最便宜？
令牌类型包括cacheRead（缓存读取）、cacheCreation（缓存创建）、input（输入）和output（输出）。其中cacheRead最便宜，且在长会话中占主导。
如何通过追踪查看Claude Code的子代理调用？
在Jaeger UI中，选择服务claude-code，按session.id标签搜索，可以找到对应的追踪。每个追踪包含多个span，如claude_code.interaction、claude_code.llm_request和claude_code.tool，可以查看子代理的调用和耗时。
Claude Code的遥测数据中，用户提示词是否会被记录？
默认情况下，用户提示词在交互span中被脱敏，不会记录原始文本。如果设置OTEL_LOG_USER_PROMPTS=1，则会记录原始提示词，但建议在多租户环境中避免启用，以免泄露提示内容。
Claude Code的指标默认使用哪种聚合时间性？为什么需要改为累积？
默认使用Delta（增量）时间性，即每次导出的是自上次导出以来的变化量。但Prometheus的rate()和increase()函数期望累积值，因此需要设置OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative来改为累积模式。
