Skip to content

README_OTEL.md

Latest commit

 

History

History
94 lines (69 loc) · 3.21 KB

README_OTEL.md

File metadata and controls

94 lines (69 loc) · 3.21 KB

Monitoring Claude Usage via OpenTelemetry

Claude Code Setup

Once you deploy the worker to the https://cc-monitor.your-org.workers.dev, you can enable monitoring with env settings like:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://cc-monitor.your-org.workers.dev",

    "OTEL_METRIC_EXPORT_INTERVAL": 3000,

    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer token"
  }
}
  • OTEL_METRIC_EXPORT_INTERVAL: Specify a short interval to minimize data loss.
  • OTEL_EXPORTER_OTLP_HEADERS: See the security section below.

You can leverage your company's MDM solution to deploy this as org-managed settings.

See more details from the Claude Code official guide.

How to Query

You can query the collected data in the Cloudflare Console (Analytics Engine Studio), Cloudflare API or Grafana Dashboard.

Analytics Engine Schema

Table Name: claude_code_metrics_v20250717

Blobs (Fixed Schema):

  • blob1: metric_type (session_count, cost_usage, etc.)
  • blob2: service.name (e.g. claude-code)
  • blob3: service.version (e.g. 1.0.48)
  • blob4: organization.id (UUID, optional)
  • blob5: user.id (hashed user ID)
  • blob6: user.account_uuid (UUID, optional)
  • blob7: user.email (email address, optional)
  • blob8: session.id (UUID)
  • blob9: terminal.type (e.g. iTerm, optional)
  • blob10+: Metric-specific attributes

Doubles:

  • double1: timestamp_ms - Timestamp in milliseconds
  • double2: metric_value - The actual metric value

Supported Metrics

The endpoint processes the following Claude Code metrics:

Metric Name Description Additional Attributes
session_count CLI session starts
cost_usage Usage costs in USD blob10 (model)
token_usage Token consumption blob10 (model), blob11 (token_type)
active_time_total Active time tracking
lines_of_code Code changes
pull_request_count PR creation events
commit_count Commit events
code_edit_tool_decision Tool decisions blob11 (decision), blob12 (language), blob13 (tool_name)

Example Analytics Engine Query

SELECT 
  blob1 as metric_type,
  blob7 as user_email,
  SUM(double2) as total_value
FROM {{TABLE_NAME}}
WHERE metric_type = 'cost_usage'
GROUP BY metric_type, user_email
ORDER BY total_value DESC

Architecture

Claude Code → OTLP/HTTP → Cloudflare Worker → Analytics Engine

The worker acts as a bridge between Claude Code's OTLP metrics and Cloudflare's Analytics Engine:

  1. Receives OTLP metrics via HTTP/JSON POST requests
  2. Authenticates requests using Bearer token validation
  3. Transforms OTLP data to Analytics Engine format
  4. Stores metrics in Analytics Engine for querying