Telemetry and tracing
This page owns the traffic, telemetry, analytics, and tracing/export side of the ops layer. It separates observability transport from local debug logs and from feature-gate decision logic.
Use Diagnostics and debug logs for local debug evidence, Feature gates reference for GrowthBook/tengu_* feature gates, and Environment variables reference for the canonical env-var list.
Source anchors
| Semantic alias | Source | Approximate location | String or symbol | Meaning |
|---|---|---|---|---|
| EssentialTrafficGate | cli.js | line ~133, byte 0xea146 | CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | Coarse traffic gate: essential traffic only. |
| DisableTelemetryGate | cli.js | line ~133, byte 0xea198 | DISABLE_TELEMETRY | Telemetry disable gate. |
| DoNotTrackGate | cli.js | line ~133, byte 0xea1d1 | DO_NOT_TRACK | Telemetry disable gate. |
| DisableErrorReportingGate | cli.js | line ~133, byte 0xea692 | DISABLE_ERROR_REPORTING | Error-reporting disable gate. |
| OtelHeadersEnv | cli.js | line ~2630, byte 0x654a73 | OTEL_EXPORTER_OTLP_HEADERS | OpenTelemetry exporter env surface. |
| TraceExportPath | cli.js | line ~2709, byte 0x72d66f | /v1/traces | Beta/OTEL trace export path. |
| LogExportPath | cli.js | line ~2709, byte 0x72d69c | /v1/logs | Beta/OTEL log export path. |
| TraceparentEnv | cli.js | line ~2027, byte 0x526c31 | TRACEPARENT | Trace-context propagation. |
| AnalyticsFlushHook | cli.js | line ~1676, byte 0x4fb763 | flushAnalyticsSinks | Shutdown-time analytics/log/trace flush. |
Traffic policy
The traffic gate visible near line ~133 distinguishes coarse network policy from telemetry-specific disablement.
| Condition | Runtime traffic mode |
|---|---|
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set | essential-traffic |
DISABLE_TELEMETRY is set | no-telemetry |
DO_NOT_TRACK is truthy | no-telemetry |
| none of the above | default |
This distinction matters because essential traffic can still allow network calls required for core operation, while telemetry/error-reporting sinks are reduced or disabled.
Telemetry signal families
cli.js contains many tengu_* strings. In this wiki, they are treated as operational signal names unless surrounding source confirms a product behavior. Common families include:
| Family | Examples | Interpretation |
|---|---|---|
| Tool/security | tengu_tool_use_can_use_tool_allowed, tengu_tool_use_can_use_tool_rejected | Tool permission outcomes and security decisions. |
| MCP/plugins | tengu_mcp_tool_call_auth_error, plugin install/update signals | Integration health and auth failures. |
| Agents/scheduling | scheduled-task, auto-mode, background-agent signals | Agent/task runtime observability. |
| Remote/bridge | bridge state, remote backend, CCR-style signals | Remote Control and bridge operation. |
| Updater | tengu_native_auto_updater_* | Native updater lifecycle. |
| API/model usage | API request duration, token, cost, retry, and quota signals | Provider-call accounting and support evidence. |
OpenTelemetry and trace export
| Surface | Role |
|---|---|
TRACEPARENT, TRACESTATE | W3C trace-context propagation into subprocess/session env when available. |
BETA_TRACING_ENDPOINT | If set, beta exporter delegates to ${endpoint}/v1/traces and ${endpoint}/v1/logs. |
OTEL_EXPORTER_OTLP_ENDPOINT | Standard OTLP endpoint. |
OTEL_EXPORTER_OTLP_PROTOCOL and per-signal protocol envs | Selects grpc, http/json, or http/protobuf exporters. |
OTEL_EXPORTER_OTLP_HEADERS | Header configuration for OTLP export. |
OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER | Selects metrics/log exporters such as console, OTLP, or prometheus. |
OTEL_LOG_TOOL_DETAILS, OTEL_LOG_TOOL_CONTENT, OTEL_LOG_USER_PROMPTS | Controls how much tool/user detail can be logged. |
--add-trace-attribute key=value | Adds runtime trace attributes. |
The source installs final flush hooks on exit paths, so logs/traces get a best-effort drain during shutdown.
Error reporting
Error reporting is controlled separately from telemetry. DISABLE_ERROR_REPORTING, provider-specific modes, and essential-traffic mode can short-circuit external error reporting even when local debug logs exist.
Safe interpretation rules
- Treat
tengu_*as evidence of telemetry or a feature gate, not as a stable public event schema. - Do not infer live network behavior from static endpoint strings alone.
- Keep sensitive values out of logs; env-var names can be documented, values should not be captured.
- Use Diagnostics and debug logs for file/stdout/stderr debug evidence.
Related docs
Created and maintained by Yingting Huang.