[FEATURE] Export usage limit utilization via OTEL metrics

[JuanjoFuchs]

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code exports useful OTEL metrics (cost, tokens, session info), but usage limit utilization is not included. This means users building observability dashboards cannot track how close they are to hitting their 5-hour rolling or 7-day limits.

Currently, the only ways to access this data are:

• The /usage command (manual, not programmatic)
• The OAuth Usage API (requires separate polling, not integrated with OTEL pipeline)

Related issues request this data for statusLine hooks (#15366, #12520), but there's no way to get it into Prometheus/Grafana/Datadog via the existing OTEL export.

Use Case

I'm building an observability stack for Claude Code using the native OTEL export. I can track:

• Cost over time ✅
• Token usage by type ✅
• Tool calls ✅
• API requests ✅

But I cannot answer: "How close am I to my usage limit?"

This forces me to run a separate exporter that polls the Usage API, duplicating infrastructure that Claude Code already has access to internally.

Proposed Solution

Add new OTEL metrics for usage limit data:

# Gauge: Current utilization (0.0 to 1.0)
claude_code.usage.utilization{limit="5h_rolling"} 0.62
claude_code.usage.utilization{limit="7d_all_models"} 0.42
claude_code.usage.utilization{limit="7d_sonnet"} 0.38

# Gauge: Reset timestamp (Unix seconds)
claude_code.usage.resets_at{limit="5h_rolling"} 1736350560
claude_code.usage.resets_at{limit="7d_all_models"} 1736640000
claude_code.usage.resets_at{limit="7d_sonnet"} 1736640000

These would be exported alongside existing metrics when OTEL_METRICS_EXPORTER=otlp is configured.

Alternative Solutions

1. Do nothing - Users continue running separate exporters to poll the Usage API
2. Document the Usage API - Help users build their own exporters (current workaround)
3. Add to statusLine only - Partially addressed by #15366, but doesn't help OTEL users

Priority

Medium - Would be very helpful

Feature Category

Monitoring and telemetry

Additional Context

The data already exists internally - Claude Code displays it in the UI and exposes it via /usage. This request is to include it in the OTEL export pipeline for users who want to build dashboards and alerts.

Example dashboard use case:

• Alert when 5h utilization > 80%
• Visualize burn rate over time
• Correlate usage spikes with specific activities