Claude Code Monitoring

Track your Claude Code usage with Mini Metrics. Claude Code supports OpenTelemetry (OTel) metrics, which can be forwarded to Mini Metrics via an OpenTelemetry Collector.

Overview

This guide shows you how to set up an OpenTelemetry Collector to receive metrics from Claude Code and forward them to Mini Metrics. The setup involves:

Running an OpenTelemetry Collector (via Docker)
Configuring Claude Code to send metrics to the collector
The collector forwards metrics to Mini Metrics

Step 1: Create the Collector Configuration

Create a file called otel-collector-config.yaml:

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

processors:
  batch:
    timeout: 10s

exporters:
  otlphttp:
    endpoint: https://mnmt.dev
    headers:
      x-api-key: YOUR_MINIMETRICS_API_KEY

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

Replace YOUR_MINIMETRICS_API_KEY with your actual API key from the Mini Metrics dashboard.

Step 2: Create Docker Compose File

Create a docker-compose.yaml file:

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel-collector-config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml:ro
    ports:
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP

Step 3: Start the Collector

Run the collector:

docker compose up -d

Step 4: Configure Claude Code

Set the following environment variables before running Claude Code:

# Enable telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# Configure OTLP exporter
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Optional: reduce export interval for testing (default: 60000ms)
export OTEL_METRIC_EXPORT_INTERVAL=10000

# Run Claude Code
claude

For persistent configuration, add these to your shell profile (~/.bashrc or ~/.zshrc).

Available Metrics

Claude Code exports the following metrics that will appear in Mini Metrics:

claude_code.session.count

Count of CLI sessions started

claude_code.token.usage

Number of tokens used (input, output, cache)

claude_code.cost.usage

Estimated cost of Claude Code sessions in USD

claude_code.lines_of_code.count

Lines of code added or removed

claude_code.commit.count

Number of git commits created

claude_code.pull_request.count

Number of pull requests created

claude_code.active_time.total

Total active time in seconds

Configuration Options

Common environment variables for Claude Code telemetry:

Variable	Description
CLAUDE_CODE_ENABLE_TELEMETRY	Enable telemetry (required, set to 1)
OTEL_METRICS_EXPORTER	Exporter type: otlp, prometheus, console
OTEL_EXPORTER_OTLP_PROTOCOL	Protocol: grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT	Collector endpoint (e.g., http://localhost:4317)
OTEL_METRIC_EXPORT_INTERVAL	Export interval in ms (default: 60000)

Team Configuration

For organizations with multiple teams, add custom attributes to segment your data:

export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform"

These attributes will be included in all metrics, allowing you to filter by team in Mini Metrics.

Troubleshooting

No metrics appearing?

• Verify the collector is running: docker compose ps
• Check collector logs: docker compose logs otel-collector
• Ensure CLAUDE_CODE_ENABLE_TELEMETRY=1 is set
• Try reducing OTEL_METRIC_EXPORT_INTERVAL to 10000 for faster feedback

Debug with console output

Set OTEL_METRICS_EXPORTER=console to see metrics printed to stdout.