# OpenClaw Usage Exporter

FastAPI Prometheus exporter for OpenClaw usage, session, and runtime-adjacent metrics.

## What it exports

Reads OpenClaw session data from disk and exposes `/metrics` with as much non-sensitive data as possible.

### Why timeframe switching looked wrong before

Prometheus scrapes snapshots. The old exporter leaned heavily on "today so far" gauges, so a Grafana timeframe change could look almost unchanged unless the panel query explicitly used range math.

The exporter now also exposes:

- monotonic all-time counters for tokens, cost, and usage entries
- retained daily buckets
- retained hourly buckets

That gives dashboards something real to aggregate over a selected time range.

### Daily usage metrics

- `openclaw_daily_total_tokens`
- `openclaw_daily_input_tokens`
- `openclaw_daily_output_tokens`
- `openclaw_daily_cache_read_tokens`
- `openclaw_daily_cache_write_tokens`
- `openclaw_daily_reasoning_tokens`
- `openclaw_daily_usage_entries`
- `openclaw_daily_cost_input`
- `openclaw_daily_cost_output`
- `openclaw_daily_cost_cache_read`
- `openclaw_daily_cost_cache_write`
- `openclaw_daily_cost_total`
- `openclaw_daily_message_records`
- `openclaw_daily_non_message_records`
- `openclaw_daily_unique_sessions`
- `openclaw_daily_unique_models`
- `openclaw_daily_unique_providers`

### Daily breakdowns

- `openclaw_daily_messages_total{role=...}`
- `openclaw_daily_stop_reasons_total{stop_reason=...,model=...,provider=...}`
- `openclaw_daily_tool_calls_total{tool_name=...}`
- `openclaw_daily_errors_total{error_type=...}`
- `openclaw_daily_model_total_tokens{model=...,provider=...}`
- `openclaw_daily_model_input_tokens{model=...,provider=...}`
- `openclaw_daily_model_output_tokens{model=...,provider=...}`
- `openclaw_daily_model_reasoning_tokens{model=...,provider=...}`
- `openclaw_daily_session_total_tokens{session_id=...}`
- `openclaw_daily_session_input_tokens{session_id=...}`
- `openclaw_daily_session_output_tokens{session_id=...}`
- `openclaw_daily_session_messages_total{session_id=...,role=...}`
- `openclaw_daily_session_errors_total{session_id=...}`
- `openclaw_daily_session_tool_calls_total{session_id=...,tool_name=...}`

### Session inventory metrics

Derived from `sessions.json`:

- `openclaw_sessions_visible_count`
- `openclaw_sessions_total_count`
- `openclaw_sessions_has_more`
- `openclaw_session_info{session_id=...,status=...,chat_type=...,last_channel=...,model=...,provider=...,auth_profile_override=...,system_sent=...,aborted_last_run=...,total_tokens_fresh=...}`
- `openclaw_session_age_seconds{session_id=...}`
- `openclaw_session_updated_timestamp_seconds{session_id=...}`
- `openclaw_session_started_timestamp_seconds{session_id=...}`
- `openclaw_session_last_interaction_timestamp_seconds{session_id=...}`
- `openclaw_session_total_tokens{session_id=...}`
- `openclaw_session_input_tokens{session_id=...}`
- `openclaw_session_output_tokens{session_id=...}`
- `openclaw_session_context_tokens{session_id=...}`
- `openclaw_session_runtime_seconds{session_id=...}`
- `openclaw_session_estimated_cost_usd{session_id=...}`
- `openclaw_session_compaction_count{session_id=...}`
- `openclaw_session_usage_family_session_count{session_id=...}`

### Time-range-friendly counters and buckets

- `openclaw_total_tokens_total`
- `openclaw_input_tokens_total`
- `openclaw_output_tokens_total`
- `openclaw_cache_read_tokens_total`
- `openclaw_cache_write_tokens_total`
- `openclaw_reasoning_tokens_total`
- `openclaw_usage_entries_total`
- `openclaw_cost_input_usd_total`
- `openclaw_cost_output_usd_total`
- `openclaw_cost_cache_read_usd_total`
- `openclaw_cost_cache_write_usd_total`
- `openclaw_cost_total_usd_total`
- `openclaw_message_records_total`
- `openclaw_non_message_records_total`
- `openclaw_model_total_tokens_total{model=...,provider=...}`
- `openclaw_model_input_tokens_total{model=...,provider=...}`
- `openclaw_model_output_tokens_total{model=...,provider=...}`
- `openclaw_session_total_tokens_total{session_id=...}`
- `openclaw_day_total_tokens{date=...,tz=...}`
- `openclaw_day_cost_total{date=...,tz=...}`
- `openclaw_day_usage_entries{date=...,tz=...}`
- `openclaw_hour_total_tokens{hour=...,tz=...}`
- `openclaw_hour_cost_total{hour=...,tz=...}`
- `openclaw_hour_usage_entries{hour=...,tz=...}`

### Exporter/runtime metrics

- `openclaw_exporter_files_scanned`
- `openclaw_exporter_lines_scanned`
- `openclaw_exporter_parse_errors`
- `openclaw_exporter_negative_cost_entries_skipped`
- `openclaw_exporter_negative_cost_fields_skipped{cost_field=...}`
- `openclaw_exporter_negative_cost_amount_skipped{cost_field=...}`
- `openclaw_exporter_history_days_retained`
- `openclaw_exporter_history_hours_retained`
- `openclaw_usage_cost_cache_files_tracked`
- `openclaw_usage_cost_cache_version`
- `openclaw_usage_cost_cache_updated_timestamp_seconds`

## Privacy boundary

This exporter intentionally skips obvious revealing fields like message content, sender labels, sender ids, phone numbers, response ids, idempotency keys, and session keys.

Session ids are exported.

It also ignores invalid negative cost values found in some legacy/raw usage records and exposes exporter metrics for how many were skipped.

## Code layout

- `app.py` keeps the uvicorn entrypoint tiny
- `openclaw_usage_exporter/config.py` holds env-driven paths and retention settings
- `openclaw_usage_exporter/models.py` holds report dataclasses and cost handling
- `openclaw_usage_exporter/collectors.py` reads session files and cache/index data
- `openclaw_usage_exporter/metrics.py` renders Prometheus output
- `openclaw_usage_exporter/utils.py` keeps shared helpers small

## Run locally

```bash
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 9487
```

## Runtime

- Canonical repo path: `/root/projects/openclaw-usage-exporter`
- Compatibility workspace path: `/root/.openclaw/workspace/openclaw-daily-tokens-exporter`
- systemd user unit: `~/.config/systemd/user/openclaw-daily-tokens-exporter.service`
- Direct metrics: `http://100.74.255.106:9487/metrics`
- Tailscale Serve path: `https://luna.taile7522.ts.net/openclaw-daily-tokens`

## Env

- `OPENCLAW_SESSIONS_DIR` default: `/root/.openclaw/agents/main/sessions`
- `OPENCLAW_EXPORTER_TZ` default: `Europe/Berlin`
- `OPENCLAW_SESSIONS_INDEX` default: `/root/.openclaw/agents/main/sessions/sessions.json`
- `OPENCLAW_USAGE_COST_CACHE` default: `/root/.openclaw/agents/main/sessions/.usage-cost-cache.json`
- `OPENCLAW_HISTORY_DAYS` default: `30`
- `OPENCLAW_HISTORY_HOURS` default: `168`
- `PORT` ignored by app directly; set it in the service or uvicorn command