CodeBuddy Code 支持把 traces 通过标准 OTLP 协议上报到用户自有的 OpenTelemetry Collector，便于企业自建可观测性平台对接。
当前范围：
支持 traces（链路追踪）+ 4 个隐私 opt-in 开关。暂不支持 metrics 与 logs 的自定义上报。
快速开始
# 1. 启用 telemetryexport CODEBUDDY_CODE_ENABLE_TELEMETRY=1# 2. 配置 OTLP endpointexport OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318# 3. (可选) 启用隐私 opt-in 内容记录export OTEL_LOG_USER_PROMPTS=1export OTEL_LOG_TOOL_DETAILS=1export OTEL_LOG_TOOL_CONTENT=1# 4. 运行codebuddy
说明：
兼容 Claude Code 配置：
CLAUDE_CODE_ENABLE_TELEMETRY 与 CODEBUDDY_CODE_ENABLE_TELEMETRY 等价。配置变量
基础配置
变量 | 用途 | 示例 |
CODEBUDDY_CODE_ENABLE_TELEMETRY | 启用 OTel 上报（必需） | 1 |
OTEL_TRACES_EXPORTER | Exporter 类型 | otlp（默认）、console、none |
OTEL_EXPORTER_OTLP_ENDPOINT | OTLP Collector 地址，自动追加 /v1/traces | http://localhost:4318 |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | Traces 专用完整 URL，优先级更高 | http://localhost:4318/v1/traces |
OTEL_EXPORTER_OTLP_HEADERS | 请求头 k1=v1,k2=v2，value 支持 URL 编码 | Authorization=Bearer%20token |
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL | 传输协议 | http/protobuf（仅支持） |
OTEL_SERVICE_NAME | 覆盖默认 service.name | codebuddy-code |
OTEL_RESOURCE_ATTRIBUTES | 附加 resource 属性 | team=platform,env=prod |
隐私 opt-in 开关
Span 默认不记录任何敏感信息（prompt 内容、工具参数、工具输出等），需要通过以下环境变量逐级 opt-in：
变量 | 用途 | 记录的内容 |
OTEL_LOG_USER_PROMPTS=1 | 记录用户 prompt | user_prompt 属性（默认为不记录，仅记录 user_prompt_length） |
OTEL_LOG_TOOL_DETAILS=1 | 记录工具参数 | tool_input 属性（~4KB 截断）+ 工具特定属性（file.path、command 等） |
OTEL_LOG_TOOL_CONTENT=1 | 记录工具输入输出全文 | tool_input/tool_result span events（60KB 截断） |
OTEL_LOG_RAW_API_BODIES=1 | 记录完整 API 请求/响应体 | 预留，暂未实现 |
GenAI 语义约定开关（agentLens / 智研 LLM 监控）
默认上报使用 CodeBuddy 自有命名（
codebuddy_code.* span、span.type 等）。如需对接 agentLens（腾讯智研 LLM 监控，基于 OTel），通过 OTEL_SEMCONV 追加 gen_ai.* 语义约定字段（只增不删，保留全部原字段）：值 | 含义 |
codebuddy（默认，缺省） | 不写任何新字段，行为与现状完全一致 |
agentlens | 启用 agentLens 语义，追加 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 类型（ span.type） | gen_ai.span.kind | 关键字段 |
interaction（入口） | AGENT | gen_ai.user.time_to_first_token、input.value / output.value |
subagent（嵌套） | AGENT | gen_ai.operation.name |
model_stream（LLM 调用） | LLM | gen_ai.system / model_name / request.model / request.parameters / response.time_to_first_token / response.finish_reason / usage.input_tokens / usage.output_tokens / usage.total_tokens / input.value / output.value |
tool / user_input_wait | TOOL | tool.name / tool.parameters / input.value / output.value |
mcp_call | TOOL | tool.name / gen_ai.mcp.server_name / gen_ai.mcp.tool_name |
context_compact / session_replay / teammate_busy | TASK | — |
model_request | （不上报） | 见下方说明 |
通用字段（所有 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属性 | 描述 | 受控于 |
span.type | 固定值 "interaction" | - |
conversation.id | 会话 ID | - |
conversation.agent | Agent 名称 | - |
user_prompt | 用户 prompt 内容（未启用时不记录） | OTEL_LOG_USER_PROMPTS |
user_prompt_length | Prompt 长度（始终记录） | - |
conversation.cancelled | 会话被取消时为 true | - |
codebuddy_code.tool属性 | 描述 | 受控于 |
span.type | 固定值 "tool" | - |
tool_name | 工具名称 | - |
tool.call_id | 工具调用 ID（始终记录） | - |
file.path | 文件路径（Read/Write/Edit） | OTEL_LOG_TOOL_DETAILS |
command | Bash 命令 | OTEL_LOG_TOOL_DETAILS |
command.timeout | 命令超时（毫秒） | OTEL_LOG_TOOL_DETAILS |
glob.pattern | Glob 搜索模式 | OTEL_LOG_TOOL_DETAILS |
grep.pattern | Grep 正则模式 | OTEL_LOG_TOOL_DETAILS |
http.url | WebFetch URL | OTEL_LOG_TOOL_DETAILS |
search.query | WebSearch 查询 | OTEL_LOG_TOOL_DETAILS |
agent.prompt | 子 Agent prompt | OTEL_LOG_TOOL_DETAILS |
agent.type | 子 Agent 类型 | OTEL_LOG_TOOL_DETAILS |
mcp.server | MCP 服务器名 | OTEL_LOG_TOOL_DETAILS |
mcp.tool | MCP 工具名 | OTEL_LOG_TOOL_DETAILS |
tool_input | 工具输入 JSON（~4KB 截断） | OTEL_LOG_TOOL_DETAILS |
tool_input_truncated | 输入是否被截断 | OTEL_LOG_TOOL_DETAILS |
tool_input_original_length | 截断前原始长度 | OTEL_LOG_TOOL_DETAILS |
codebuddy_code.tool span events（需要 OTEL_LOG_TOOL_CONTENT=1）事件名 | 属性 | 描述 |
tool_input | content | 完整工具输入（60KB 截断） |
tool_input | content_truncated | 是否被截断 |
tool_input | content_original_length | 截断前长度 |
tool_result | content | 完整工具输出（60KB 截断） |
tool_result | content_truncated | 是否被截断 |
tool_result | content_original_length | 截断前长度 |
典型场景
上报到企业自建 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
优先级与回退
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。
协议支持
仅支持
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），确保上游分析平台可统一处理。
