claudestat-exporter-prometheus

Prometheus exporter for @statforge/claudestat — exposes Claude Code + OpenCode cost, token, quota, and tool metrics in Prometheus text format.

Install

npm install -g @statforge/claudestat-exporter-prometheus

Quick start

# 1. Ensure claudestat daemon is running
claudestat start

# 2. Start the exporter
claudestat-exporter-prometheus --port 9464

# 3. Verify
curl http://127.0.0.1:9464/metrics

Prometheus configuration

Add to your prometheus.yml:

scrape_configs:
  - job_name: 'claudestat'
    scrape_interval: 15s
    static_configs:
      - targets: ['127.0.0.1:9464']

CLI flags

claudestat-exporter-prometheus [options]

  -p, --port <number>          Listen port (default: 9464)
  -H, --host <string>          Listen host (default: 127.0.0.1)
  -d, --days <number>          Time window in days (default: 7)
  -c, --cache-ttl <seconds>    Cache TTL in seconds (default: 5)
  -t, --throw-on-no-daemon     Exit 1 if daemon unreachable on first scrape
  -v, --version                Show version
  -h, --help                   Show help

Metrics (25 custom + process defaults)

| Category | Metrics | |---|---| | Exporter health | claudestat_exporter_up, claudestat_exporter_scrape_duration_seconds, claudestat_exporter_last_scrape_error{reason} | | Sessions | claudestat_sessions_total{model,source}, claudestat_cost_usd_total{model,source}, claudestat_sessions_recent_count{source}, claudestat_latest_session_cost_usd{source}, claudestat_latest_session_tokens{source,type} | | Quota (Claude Code) | claudestat_quota_cycle_pct, claudestat_quota_cycle_tokens, claudestat_quota_cycle_limit_tokens, claudestat_quota_weekly_pct_all | | Daily activity | claudestat_tokens_daily_total{date,source}, claudestat_cost_daily_usd{date}, claudestat_tool_calls_daily_total{date} | | Tool usage | claudestat_tool_calls_total{tool,source}, claudestat_tool_duration_seconds_total{tool,source}, claudestat_tool_cost_usd_total{tool,source} | | Model breakdown | claudestat_model_session_count{model}, claudestat_model_cost_usd{model}, claudestat_model_cost_pct{model} | | Database | claudestat_db_size_bytes, claudestat_db_total_events | | Burn rate | claudestat_burn_rate_tokens_per_min |

Grafana dashboard

A pre-built dashboard is included at dashboards/claudestat-overview.json. Import via Grafana → Dashboards → Import → Upload JSON file.

Panels:

1. Cost gauge — claudestat_cost_usd_total (current spend by model)
2. Token counter — claudestat_latest_session_tokens (input/output/cache breakdown)
3. Quota cycle % — claudestat_quota_cycle_pct (5h Claude Code cycle)
4. Tool calls by name — claudestat_tool_calls_total (top 10 tools)
5. Model cost pie — claudestat_model_cost_pct
6. Daily activity — claudestat_cost_daily_usd over time

Daemon-down behavior

If the claudestat daemon is unreachable:

• claudestat_exporter_up = 0
• Business metrics retain last cached values for 300s
• After 300s: metrics emit NaN (Prometheus "no data" convention)
• Use --throw-on-no-daemon to exit 1 instead (for systemd managed deployments)

Requirements

• Node.js >= 22 (for node:sqlite in claudestat)
• @statforge/claudestat daemon running (claudestat start)

License

MIT — see LICENSE