Monitoring CodeBuddy Code with OpenTelemetry ​

CodeBuddy Code supports exporting internal traces to your own OpenTelemetry Collector via the standard OTLP protocol, making it easy to integrate with self-hosted observability platforms.

MVP Scope: Currently only traces (distributed tracing) are supported; custom export of metrics and logs is not yet available. Support will be expanded as needed.

How to Enable ​

Once the enable switch is set, traces will be exported using OTel standard environment variables:

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

A legacy alias CLAUDE_CODE_ENABLE_TELEMETRY is also accepted for backward compatibility and is equivalent to CODEBUDDY_CODE_ENABLE_TELEMETRY.

Key Environment Variables ​

For the full list, see env-vars.md. Common ones:

VariablePurpose
CODEBUDDY_CODE_ENABLE_TELEMETRY=1Enable the OTel export switch
OTEL_TRACES_EXPORTERotlp (default) / console / none
OTEL_EXPORTER_OTLP_ENDPOINTOTLP Collector address; /v1/traces is appended automatically
OTEL_EXPORTER_OTLP_TRACES_ENDPOINTFull URL specific to traces; takes higher priority
OTEL_EXPORTER_OTLP_HEADERSRequest headers k1=v1,k2=v2; values support URL encoding
OTEL_SERVICE_NAMEOverride the default service.name
OTEL_RESOURCE_ATTRIBUTESAdditional resource attributes

Protocol Support ​

Only http/protobuf (OTLP/HTTP + Protobuf encoding) is supported, consistent with the CodeBuddy Code default.

Setting OTEL_EXPORTER_OTLP_PROTOCOL=grpc or http/json will be ignored with a warning logged, and will fall back to the default protobuf.

Typical Scenarios ​

1. Export to a Self-Hosted Enterprise 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. Local Debug Trace Output ​

For debugging, send traces directly to stdout:

bash
export CODEBUDDY_CODE_ENABLE_TELEMETRY=1
export OTEL_TRACES_EXPORTER=console

3. Temporarily Disable ​

bash
export OTEL_TRACES_EXPORTER=none
# Or globally disable:
export DISABLE_TELEMETRY=1

Priority and Fallback ​

  1. DISABLE_TELEMETRY=1 has the highest priority and disables all telemetry.
  2. Enable evaluation: enabled in the built-in product configuration or CODEBUDDY_CODE_ENABLE_TELEMETRY (or its legacy alias CLAUDE_CODE_ENABLE_TELEMETRY) is set to a truthy value (1 / true / yes / on).
  3. Endpoint priority: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT > OTEL_EXPORTER_OTLP_ENDPOINT > telemetry.tracing.url in the built-in product configuration.
  4. Headers: env and product configuration are merged; env keys with the same name override product configuration.

FAQ ​

Will prompts or code content be written into traces? ​

No. CodeBuddy Code traces only record structured metrics such as tool calls, model calls, and durations. They do not contain user conversation content or source code. If you need to record code snippets, you must separately enable the standard reporting channel (which is outside the scope of this feature).

Does it conflict with the internal enterprise reporting channel? ​

No conflict. OTel custom export and the built-in standard reporting (telemetry.report.standard) are two independent channels and can be enabled simultaneously.

Is metrics / logs supported? ​

Not yet supported, but planned. If you have a strong need, please provide feedback on the corresponding Issue.