Claude Code OpenTelemetry for pi

One observability stack for every coding agent

Your telemetry should not fragment when your tools do.

This pi package makes pi speak Claude Code's OpenTelemetry metrics language: same eight metric families, same units, and dashboard-compatible attributes. Pi lands in your existing collector, Prometheus backend, and Grafana dashboard 25255 beside Claude Code.

One install. No migration. No second dashboard.

Install in one command

pi install npm:claude-code-opentelemetry

Restart pi. Existing Claude Code telemetry configuration is reused automatically.

Already exporting Claude Code metrics? Install, restart, done. Extension reads same CLAUDE_CODE_ENABLE_TELEMETRY and OTEL_* environment variables.

Why teams choose it

| Without this extension | With this extension | |---|---| | Separate pi_* metrics and dashboards | Claude Code-compatible metric schema | | Collector transforms and recording rules | Direct OTLP/HTTP protobuf export | | Split cost and usage views | Pi and Claude Code in dashboard 25255 | | Custom maintenance burden | Standard pi package updates | | Unclear approximation semantics | Explicit, documented compatibility contract |

pi update npm:claude-code-opentelemetry

Quick start

1. Configure OTLP metrics

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative

Extension sends OTLP/HTTP protobuf to http://localhost:4318/v1/metrics. Default export interval is 60 seconds; set OTEL_METRIC_EXPORT_INTERVAL to change it.

2. Run pi

pi

3. Import Grafana dashboard 25255

1. Open Dashboards → New → Import in Grafana.
2. Enter dashboard ID 25255.
3. Select Prometheus-compatible data source receiving your collector's metrics.

Pi data appears under service_name="pi-coding-agent". Existing Claude Code data remains unchanged.

What gets exported

| OpenTelemetry metric | Prometheus series used by dashboard 25255 | Measures | |---|---|---| | claude_code.session.count | claude_code_session_count_total | Sessions started | | claude_code.token.usage | claude_code_token_usage_tokens_total | Input, output, cache-read, and cache-creation tokens | | claude_code.cost.usage | claude_code_cost_usage_USD_total | Provider-reported cost in USD | | claude_code.lines_of_code.count | claude_code_lines_of_code_count_total | Added and removed lines | | claude_code.commit.count | claude_code_commit_count_total | Git commits created | | claude_code.pull_request.count | claude_code_pull_request_count_total | GitHub pull requests and GitLab merge requests created | | claude_code.code_edit_tool.decision | claude_code_code_edit_tool_decision_total | Successful edit/write decisions | | claude_code.active_time.total | claude_code_active_time_seconds_total | CLI and estimated user-active seconds |

Dashboard attributes include organization_id, user_email, session_id, model, type, decision, and language. Zero-valued series are initialized at session start so every dashboard panel is discoverable before its first matching action.

Compatibility contract

This project targets Claude Code metrics and Grafana compatibility, not behavioral identity.

| Signal | Pi measurement | |---|---| | Session start | Mapped to fresh, resume, or continue from pi lifecycle events | | Token usage | Taken from each assistant turn's pi usage block | | Cost | Taken from provider-reported pi turn cost | | Lines changed | Diffed locally before and after successful Edit/Write operations | | Commits | Counted only when an observed git commit advances HEAD | | Pull requests | Counted only when successful gh pr create or glab mr create output contains a new PR/MR URL | | Edit decisions | Emitted as accept with source config; pi has no Claude Code permission-decision event | | CLI active time | Measured wall-clock agent processing time | | User active time | Bounded interaction estimate; pi does not expose Claude Code's keyboard-focus tracker |

These differences are deliberate and documented. Metric names, units, and dashboard-facing attributes remain compatible; Pi-specific observations use closest available semantics.

Configuration

Exporters

OTEL_METRICS_EXPORTER accepts comma-separated values:

• otlp — OTLP/HTTP protobuf
• console — diagnostic output to stderr/stdout
• none — disabled

This extension exports metrics only. It does not emit Claude Code events, logs, or beta traces. Set OTEL_TRACES_EXPORTER=none when your collector has no traces pipeline.

Endpoints

| Variable | Behavior | |---|---| | OTEL_EXPORTER_OTLP_ENDPOINT | Generic endpoint; extension appends /v1/metrics | | OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | Metrics-specific endpoint; used verbatim and takes precedence |

Examples:

# Generic OTLP/HTTP endpoint
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com
# Sends to https://otel.example.com/v1/metrics

# Explicit metrics endpoint
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://otel.example.com/custom/metrics

Authentication headers

Generic and metrics-specific OTLP headers are supported. Metrics-specific values override duplicate generic keys.

export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20token'
# or
export OTEL_EXPORTER_OTLP_METRICS_HEADERS='Authorization=Bearer%20token'

Percent-encoded names and values are decoded before export. Headers are passed only to configured OTLP endpoint and never recorded as metric attributes.

Identity and cardinality

| Attribute | Source | |---|---| | organization.id | CLAUDE_CODE_ORGANIZATION_ID; otherwise first label of Git email domain; otherwise local | | user.email | Global git config user.email, when available | | user.id | Random installation ID stored with mode 0600 under ~/.pi/agent/state/otel-user-id | | session.id | Pi session UUID | | terminal.type | Terminal environment | | Resource attributes | OTEL_RESOURCE_ATTRIBUTES |

Claude-compatible cardinality controls:

• OTEL_METRICS_INCLUDE_SESSION_ID — default true
• OTEL_METRICS_INCLUDE_VERSION — default false
• OTEL_METRICS_INCLUDE_ENTRYPOINT — default false
• OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES — default true

Custom resource attributes cannot override built-in standard attributes.

Collector example

No collector change is required when Grafana dashboard 25255 already works for Claude Code. For a new OpenTelemetry Collector deployment, this minimal pipeline forwards OTLP metrics to Prometheus remote write:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch: {}

exporters:
  prometheusremotewrite:
    endpoint: https://prometheus.example.com/api/v1/write
    resource_to_telemetry_conversion:
      enabled: true

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheusremotewrite]

resource_to_telemetry_conversion exposes resource attributes such as service.name as Prometheus labels such as service_name, which dashboard 25255 queries.

Privacy model

Extension exports numeric metrics and metadata—not conversation or code content.

Never exported:

• prompts or assistant responses
• source-code contents or file paths
• tool arguments or tool output
• shell commands
• API keys or OTLP header values

To calculate line deltas and detect commits/PRs, extension inspects edited files and relevant tool results locally in memory. Raw content is discarded after measurement and never sent to collector.

Exported metadata can include Git email, hostname, anonymous installation ID, session ID, model, terminal type, language, and custom OTEL_RESOURCE_ATTRIBUTES. Review collector access and retention policy before team-wide deployment. See SECURITY.md for trust boundaries and private reporting.

Verify and troubleshoot

Inside pi:

/claude-metrics-status

Expected status shows active metrics endpoint. Query Prometheus-compatible backend:

claude_code_session_count_total{service_name="pi-coding-agent"}

If no series appears:

1. Confirm CLAUDE_CODE_ENABLE_TELEMETRY=1.
2. Confirm OTEL_METRICS_EXPORTER includes otlp or console.
3. Confirm generic or metrics-specific endpoint is set.
4. Wait one export interval, or exit pi to force a final flush.
5. Check collector logs for rejected OTLP requests.

Development

git clone https://github.com/xiaoxianma/claude-code-opentelemetry.git
cd claude-code-opentelemetry
npm install
npm run check
pi -e ./src/index.ts

Repository layout:

src/              extension and metric helpers
test/             behavior tests
media/            package-gallery and README artwork
.github/workflows continuous integration

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request.

License

MIT © xiaoxianma

Not affiliated with Anthropic, Grafana Labs, or pi maintainers. Claude Code and Grafana are trademarks of their respective owners.