监控

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

当前范围：

支持 traces（链路追踪）+ 4 个隐私 opt-in 开关。暂不支持 metrics 与 logs 的自定义上报。

快速开始

# 1. 启用 telemetry
export CODEBUDDY_CODE_ENABLE_TELEMETRY=1

# 2. 配置 OTLP endpoint
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

# 3. (可选) 启用隐私 opt-in 内容记录
export OTEL_LOG_USER_PROMPTS=1
export OTEL_LOG_TOOL_DETAILS=1
export OTEL_LOG_TOOL_CONTENT=1

# 4. 运行
codebuddy

说明：

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

配置变量

基础配置

隐私 opt-in 开关

Span 默认不记录任何敏感信息（prompt 内容、工具参数、工具输出等），需要通过以下环境变量逐级 opt-in：

GenAI 语义约定开关（agentLens / 智研 LLM 监控）

默认上报使用 CodeBuddy 自有命名（codebuddy_code.* span、span.type 等）。如需对接 agentLens（腾讯智研 LLM 监控，基于 OTel），通过 OTEL_SEMCONV 追加 gen_ai.* 语义约定字段（只增不删，保留全部原字段）：

默认关闭，存量用户零影响；停用只需取消该变量。

LLM span 的输入 / 输出（input.value / output.value）随本开关一并产出，无需额外开 OTEL_LOG_RAW_API_BODIES。但入口 span 的用户 prompt 与最终回复文本仍受 OTEL_LOG_USER_PROMPTS 门控，未开启时不记录内容。

不修改您的模型请求：token 用量（gen_ai.usage.*）取决于上游是否返回 usage；未返回时该次 LLM span 缺 token 字段，其余字段照常。如需稳定获取 token，请在业务侧请求中自带 include_usage。

启用后各类 span 携带的关键字段：

通用字段（所有 span）：gen_ai.session.id / gen_ai.user.id / gen_ai.framework / gen_ai.business.scenario（缺省不写）。

注意字段前缀：input.value / output.value / tool.name / tool.parameters 沿用 OpenInference 约定，不带 gen_ai. 前缀；gen_ai.system / gen_ai.model_name / gen_ai.mcp.* 等则带前缀。

model_request 不上报：它是模型调用的 HTTP 请求辅助 span，与承载推理的 model_stream 成对出现，两者同时上报会导致 LLM 调用次数、token、TTFT 重复统计。因此 agentlens 下不上报该 span；默认 codebuddy 链路仍完整保留，供本地排障。

Span 结构

每个用户 prompt 产生一个 codebuddy_code.interaction 根 span。工具调用记录为其子 span：

codebuddy_code.interaction├── codebuddy_code.tool (Read)├── codebuddy_code.tool (Bash)└── codebuddy_code.tool (Agent -> 子 agent 的 tool spans)

Span 属性

所有 span 都包含 span.type 属性标识类型。

codebuddy_code.interaction

codebuddy_code.tool

codebuddy_code.tool span events（需要 OTEL_LOG_TOOL_CONTENT=1）

典型场景

上报到企业自建 Collector

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

本地调试（console 输出）

export CODEBUDDY_CODE_ENABLE_TELEMETRY=1export OTEL_TRACES_EXPORTER=consoleexport OTEL_LOG_USER_PROMPTS=1export OTEL_LOG_TOOL_DETAILS=1export OTEL_LOG_TOOL_CONTENT=1

关闭 telemetry

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

优先级与回退

DISABLE_TELEMETRY=1 拥有最高优先级，关闭所有遥测。

启用判定：内置 product 配置启用 或 CODEBUDDY_CODE_ENABLE_TELEMETRY / CLAUDE_CODE_ENABLE_TELEMETRY 设置为 truthy 值（1 / true / yes / on）。

Endpoint 优先级：OTEL_EXPORTER_OTLP_TRACES_ENDPOINT > OTEL_EXPORTER_OTLP_ENDPOINT > 内置 product 配置中的 telemetry.tracing.url。

Headers：env 与 product 配置合并，env 同名 key 覆盖 product。

协议支持

仅支持 http/protobuf（OTLP/HTTP + Protobuf 编码），与 Claude Code 默认一致。设置 OTEL_EXPORTER_OTLP_PROTOCOL=grpc 或 http/json 会被忽略并写入告警日志，回退到默认 protobuf。

安全与隐私

Span 默认只记录工具名称和调用 ID，不包含用户 prompt、工具参数、文件内容或源代码

user_prompt_length 始终记录（仅长度），prompt 文本需要 OTEL_LOG_USER_PROMPTS=1 才会写入

工具参数（文件路径、命令等）需要 OTEL_LOG_TOOL_DETAILS=1，个别值超过 512 字符会被截断，总量限制 ~4KB

工具输入输出全文需要 OTEL_LOG_TOOL_CONTENT=1，通过 span events 记录，截断于 60KB

所有 opt-in 开关默认关闭，企业管理员可通过 managed settings 统一配置

常见问题

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

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

Q2：是否支持 metrics / logs？

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

Q3：与 Claude Code 的 OTEL 格式兼容吗？

是的。Span 命名、属性命名、截断策略均对齐 Claude Code 的约定（{product}.interaction / {product}.tool），确保上游分析平台可统一处理。