mde-claude-code-telemetry
Validate and configure Claude Code telemetry settings.json env vars against the official monitoring docs. Use when modifying OTEL env vars, debugging telemetry, or verifying settings compliance.
SKILL.md.agents/skills/mde-claude-code-telemetry/SKILL.md
GitHubClaude Code Telemetry Settings Skill
Validates .claude/settings.json env vars against the official Claude Code monitoring documentation at https://code.claude.com/docs/en/monitoring-usage.
When to use
- Adding or changing OTEL env vars in settings.json
- Debugging why telemetry data isn't appearing in the collector
- Verifying settings after a Claude Code upgrade
- Checking protocol/endpoint consistency
Quick validation
uv run mde-py telemetry verify
This runs all checks including the "Official Docs Compliance" section that validates every env var against the documented set.
Official env vars reference
The complete list of Claude Code telemetry env vars is in:
docs/research/trail/deep-reviews/claude-code-monitoring-reference.md
Core (required)
| Variable | Value | Purpose |
|---|---|---|
CLAUDE_CODE_ENABLE_TELEMETRY |
1 |
Master switch — nothing works without this |
OTEL_METRICS_EXPORTER |
otlp |
Enable metrics export |
OTEL_LOGS_EXPORTER |
otlp |
Enable events/logs export |
Protocol/endpoint (must be consistent)
| Protocol | Endpoint port | Notes |
|---|---|---|
grpc |
:4317 |
Default, most efficient |
http/json |
:4318 |
Human-readable, debuggable |
http/protobuf |
:4318 |
Compact binary over HTTP |
Privacy controls
| Variable | Default | When to enable |
|---|---|---|
OTEL_LOG_USER_PROMPTS |
0 (disabled) |
Only on self-hosted collectors — logs full prompt text |
OTEL_LOG_TOOL_DETAILS |
0 (disabled) |
Logs MCP server/tool names and skill names |
Custom attributes
Use OTEL_RESOURCE_ATTRIBUTES for project/team segmentation:
OTEL_RESOURCE_ATTRIBUTES=project=mde,environment=dev
Do NOT override service.name — Claude Code hardcodes service.name=claude-code and the OTEL JS SDK env detector will override it if you set it here, breaking dashboard queries.
Key facts
- Claude Code emits metrics and events/logs only — no traces (
OTEL_TRACES_EXPORTERis not used) - Events go via the OTEL Logs API, not the Traces API
- The meter name is
com.anthropic.claude_code - 8 metrics: session.count, lines_of_code.count, pull_request.count, commit.count, cost.usage, token.usage, code_edit_tool.decision, active_time.total
- 5 event types: user_prompt, tool_result, api_request, api_error, tool_decision
- All events share a
prompt.idUUID for correlation
Validation source code
The validation logic lives in src/mde/telemetry_verify.py:
_OFFICIAL_VARS— complete set of 22 documented env vars_check_settings_against_docs()— validates each var against the official set- Protocol/endpoint consistency checking