Monitoring CodeBuddy Code with OpenTelemetry ​

CodeBuddy Code 支持把内部 traces 通过标准 OTLP 协议上报到用户自有的 OpenTelemetry Collector，便于企业自建可观测性平台对接。

MVP 范围：当前仅支持 traces（链路追踪），暂不支持 metrics 与 logs 的自定义上报。后续会按需扩展。

启用方式 ​

设置启用开关后，traces 会按 OTel 标准环境变量上报：

bash
export CODEBUDDY_CODE_ENABLE_TELEMETRY=1
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com
codebuddy

兼容 Claude Code 已有配置：CLAUDE_CODE_ENABLE_TELEMETRY 与 CODEBUDDY_CODE_ENABLE_TELEMETRY 等价。

关键环境变量 ​

完整清单见 env-vars.md，常用项：

变量用途
CODEBUDDY_CODE_ENABLE_TELEMETRY=1启用 OTel 上报开关
OTEL_TRACES_EXPORTERotlp（默认）/ console / none
OTEL_EXPORTER_OTLP_ENDPOINTOTLP Collector 地址，会自动追加 /v1/traces
OTEL_EXPORTER_OTLP_TRACES_ENDPOINTtraces 专用完整 URL，优先级更高
OTEL_EXPORTER_OTLP_HEADERS请求头 k1=v1,k2=v2，value 支持 URL 编码
OTEL_SERVICE_NAME覆盖默认 service.name
OTEL_RESOURCE_ATTRIBUTES附加 resource 属性

协议支持 ​

仅支持 http/protobuf（OTLP/HTTP + Protobuf 编码），与 Claude Code 默认一致。

设置 OTEL_EXPORTER_OTLP_PROTOCOL=grpc 或 http/json 会被忽略并写入告警日志，回退到默认 protobuf。

典型场景 ​

1. 上报到企业自建 Collector ​

bash
export CODEBUDDY_CODE_ENABLE_TELEMETRY=1
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.corp.example.com
export OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20<TOKEN>
export OTEL_SERVICE_NAME=codebuddy-code
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=prod,team=copilot

2. 本地调试 trace 输出 ​

调试时让 traces 直接打到 stdout：

bash
export CODEBUDDY_CODE_ENABLE_TELEMETRY=1
export OTEL_TRACES_EXPORTER=console

3. 临时关闭 ​

bash
export OTEL_TRACES_EXPORTER=none
# 或全局禁用：
export DISABLE_TELEMETRY=1

优先级与回退 ​

  1. DISABLE_TELEMETRY=1 拥有最高优先级，关闭所有遥测。
  2. 启用判定：内置 product 配置启用 或 CODEBUDDY_CODE_ENABLE_TELEMETRY / CLAUDE_CODE_ENABLE_TELEMETRY 设置为 truthy 值（1 / true / yes / on）。
  3. Endpoint 优先级：OTEL_EXPORTER_OTLP_TRACES_ENDPOINT > OTEL_EXPORTER_OTLP_ENDPOINT > 内置 product 配置中的 telemetry.tracing.url。
  4. Headers：env 与 product 配置合并，env 同名 key 覆盖 product。

FAQ ​

是否会把 prompt / 代码内容写到 trace？ ​

不会。CodeBuddy Code 的 trace 仅记录工具调用、模型调用、耗时等结构化指标，不包含用户对话内容或源代码。如果需要记录代码片段需另行启用 standard 报告通道（不在本特性范围）。

与企业内部上报通道是否冲突？ ​

不冲突。OTel 自定义上报与内置 standard 报告（telemetry.report.standard）是两套独立通道，可同时启用。

是否支持 metrics / logs？ ​

暂不支持，规划中。如有强诉求请反馈到对应 Issue。