Skip to content

Commit 4c2f433

Browse files
jay-tauCopilot
andcommitted
feat(adapter/copilot): read session-state events.jsonl as default data source
Extend the `copilot` adapter to read `~/.copilot/session-state/<uuid>/events.jsonl` in addition to the existing OpenTelemetry JSONL exports, fixing the long-standing 'No usage data found' issue (ccusage#1174) for users who have not manually enabled OTel. The Copilot CLI writes per-session events with full per-model token totals on every install, so on a fresh system `ccusage copilot daily` now produces real reports without any environment setup. Behavior * New default source: `${COPILOT_CONFIG_DIR:-~/.copilot}/session-state/*/events.jsonl`. * Existing OTel source unchanged. Both are read in parallel. * Coexistence: when the same session appears in both sources, shutdown-derived entries win. Configurable via `COPILOT_OTEL_DEDUP=loose|strict|off` and the `COPILOT_PREFER_OTEL=1` inversion escape hatch. * Loader now actually deduplicates by `dedup_key` (HashMap pattern from `adapter/codebuff/loader.rs:26-33`), required for content-based keys. * Model normalization applied at pricing call sites only (both `calculate_cost_for_usage` and `missing_pricing_model_for_usage`); the raw Copilot model id is preserved on `LoadedEntry.model` for display fidelity. Empirical correctness fixes These derive from 18 rounds of multi-model code review (Opus 4.7, Opus 4.8, GPT-5.5) against the real 200-file local session-state corpus: * `usage.inputTokens` is inclusive of BOTH `cacheReadTokens` and `cacheWriteTokens` in this schema (different from OTel) - subtract both to recover the fresh-input bucket. * `data.tokenDetails` is NOT used as a source - `usage.*` and `tokenDetails.*` are independent snapshots that diverge in ~31% of resumed sessions; using `usage.*` consistently avoids cross-source blending. * Multiple `session.shutdown` events in a resumed session are per-process snapshots (verified non-monotonic), so each becomes a distinct entry keyed by `shutdown:{event.id}:{model}`. * Provider-aware reasoning rule: `gpt-*` and `claude-*` already include reasoning inside `outputTokens` (subset convention, 107/107 GPT and 48/48 Claude rows verified); `gemini-*` reports them separately (1/1 verified). Default for unknown providers is subset (cannot over-count). * Byte-oriented JSONL reading - real local data contains at least one invalid-UTF-8 file (a crashed/in-progress write); `fs::read_to_string` would abort the whole adapter. * Substring prefilter + top-level `type` re-check - other event types embed the literal string "session.shutdown" inside their arguments/content. Tests * 19 fixture-backed session-state parser tests covering token math, provider reasoning rules, model preservation, malformed/invalid-UTF-8 handling, skip rule, and resumed-session semantics. * 8 loader tests covering all dedup modes, the `COPILOT_PREFER_OTEL` inversion, pricing-via-normalization for `-1m-internal` models (raw model preserved + cost > 0 + missing_pricing_model None), and the back-compat pin that `--mode display` still yields 0 for existing OTel users. * 3 paths tests for env-var discovery and missing-directory handling. Docs In-PR per AGENTS.md cross-cutting flow: rewrites `docs/guide/copilot/index.md` (data sources, coexistence rule, troubleshooting) and adds the new env vars to `docs/guide/environment-variables.md`, `docs/guide/configuration.md`, `docs/guide/getting-started.md`, and `docs/guide/index.md`. This commit covers Piece A from the plan; Pieces B (`--mode credits`) and C (`--mode api-equiv`) follow as separate commits. Refs ccusage#1174 Co-authored-by: Copilot <[email protected]>
1 parent 1f2bcd5 commit 4c2f433

10 files changed

Lines changed: 1801 additions & 55 deletions

File tree

‎docs/guide/configuration.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ export OPENCODE_DATA_DIR="$HOME/.local/share/opencode"
5555
export AMP_DATA_DIR="$HOME/.local/share/amp"
5656
export PI_AGENT_DIR="$HOME/.pi/agent/sessions"
5757
export KILO_DATA_DIR="$HOME/.local/share/kilo"
58+
export COPILOT_CONFIG_DIR="$HOME/.copilot"
5859
export COPILOT_OTEL_FILE_EXPORTER_PATH="$HOME/.copilot/otel/copilot-otel.jsonl"
5960
```
6061

‎docs/guide/copilot/index.md‎

Lines changed: 49 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# GitHub Copilot CLI Data Source (Beta)
22

3-
> GitHub Copilot CLI support is experimental. The adapter reads local OpenTelemetry JSONL files only.
3+
> GitHub Copilot CLI support is experimental.
44
5-
ccusage can read GitHub Copilot CLI OpenTelemetry file exports as one of its supported local data sources. It uses the same reporting experience as the rest of ccusage: responsive tables, JSON output, LiteLLM-based pricing, cache token accounting, and all-source aggregation.
5+
ccusage reads two complementary local data sources from the Copilot CLI directory: the per-session event stream the CLI writes by default (`session-state/<sessionId>/events.jsonl`), and optional OpenTelemetry JSONL exports (`otel/*.jsonl`). Both are consumed automatically when present, with deduplication between them. Reporting uses the same experience as the rest of ccusage: responsive tables, JSON output, LiteLLM-based pricing, cache token accounting, and all-source aggregation.
66

77
## Focused Views
88

@@ -22,11 +22,30 @@ pnpm dlx ccusage copilot --help
2222

2323
:::
2424

25-
## Data Source
25+
## Data Sources
2626

27-
The CLI reads Copilot OpenTelemetry JSONL files from `~/.copilot/otel/*.jsonl` and also includes the explicit file pointed to by `COPILOT_OTEL_FILE_EXPORTER_PATH`.
27+
The Copilot CLI writes per-session events to `~/.copilot/session-state/<sessionId>/events.jsonl` on every install — no configuration is required. This is the primary source ccusage reads. The OpenTelemetry directory and explicit exporter file are only populated when the user has explicitly enabled OTel file export.
2828

29-
Enable these variables before starting or resuming a Copilot CLI session. Sessions that ran without OpenTelemetry file export enabled do not produce local JSONL usage data for ccusage to read.
29+
```text
30+
~/.copilot/
31+
├── session-state/ # primary source — written by default
32+
│ └── <sessionId>/
33+
│ └── events.jsonl
34+
└── otel/ # optional fallback / alternative
35+
└── *.jsonl
36+
```
37+
38+
To override the base directory, set `COPILOT_CONFIG_DIR` to point elsewhere; ccusage will look for `session-state/` and `otel/` underneath it.
39+
40+
If you previously relied on the OpenTelemetry-only path described in older versions of this guide, those exports continue to work — both sources are read in parallel and deduplicated. See [Source coexistence](#source-coexistence-otel-session-state) below.
41+
42+
### session-state event schema
43+
44+
Each `events.jsonl` file contains a stream of JSON records. The adapter reads `session.shutdown` events only; their `data.modelMetrics` map carries per-model token totals (`usage.{inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, reasoningTokens}`) and request counts. A resumed Copilot session produces multiple shutdown events in the same file — each is a per-process snapshot, summed at report time.
45+
46+
### Optional OpenTelemetry export
47+
48+
OTel export still works for users who want it. To enable, set the env vars before starting or resuming a Copilot CLI session:
3049

3150
```bash
3251
export COPILOT_OTEL_ENABLED=true
@@ -35,11 +54,7 @@ mkdir -p "$HOME/.copilot/otel"
3554
export COPILOT_OTEL_FILE_EXPORTER_PATH="$HOME/.copilot/otel/copilot-otel-$(date +%Y%m%d-%H%M%S).jsonl"
3655
```
3756

38-
```text
39-
~/.copilot/
40-
└── otel/
41-
└── *.jsonl
42-
```
57+
Without these variables, ccusage relies on the session-state source — which is the default for every Copilot CLI install.
4358

4459
## Report Views
4560

@@ -53,26 +68,39 @@ These views support `--json` for structured output, `--compact` for narrow termi
5368

5469
## What Gets Calculated
5570

56-
- **Token usage** - chat spans are preferred, with inference logs and agent-turn logs used as fallbacks.
57-
- **Cache tokens** - cache read and cache creation token attributes are counted when present.
58-
- **Reasoning tokens** - reasoning output tokens are included in total tokens and cost calculation.
59-
- **Pricing** - costs are calculated from LiteLLM pricing data using the reported model name.
71+
- **Token usage** — for session-state, `inputTokens` in the source schema already includes both cache reads and cache writes, so ccusage subtracts both to recover the "fresh" input bucket. For OTel, chat spans are preferred with inference logs and agent-turn logs as fallbacks.
72+
- **Cache tokens** — cache read and cache creation token attributes are counted from `cacheReadTokens` / `cacheWriteTokens` (session-state) or the corresponding `gen_ai.usage.cache_*` attributes (OTel).
73+
- **Reasoning tokens** — provider-dependent. For OpenAI (`gpt-*`) and Anthropic (`claude-*`) models reasoning is already inside `outputTokens` and is not double-counted. For Google (`gemini-*`) models reasoning is reported separately and is summed into the output cost bucket.
74+
- **Pricing** — costs are calculated from LiteLLM pricing data using a normalized form of the model name. The raw name (e.g. `claude-opus-4.7-1m-internal`) is preserved in JSON, the table's `Models` column, and `modelsUsed`.
75+
76+
## Source coexistence (OTel + session-state)
77+
78+
When both `~/.copilot/otel/*.jsonl` and `~/.copilot/session-state/<uuid>/events.jsonl` exist, both are loaded. To avoid double-counting, ccusage drops OTel-derived entries whose resolved `session_id` matches a session-state session. The OTel `session_id` is resolved from the existing parser priority chain (`gen_ai.conversation.id`, `copilot_chat.session_id`, `session.id`, `github.copilot.interaction_id`, `gen_ai.response.id`).
79+
80+
> Caveat: whether OTel's `session_id` matches the session-state directory UUID is not yet empirically verified across all Copilot CLI versions. If your IDs do not match, the loose default leaves both sources in place and totals can be inflated. The `COPILOT_OTEL_DEDUP=strict` setting drops OTel wholesale whenever any session-state shutdown is loaded — a conservative anti-double-count if you observe inflated totals.
6081
6182
## Environment Variables
6283

63-
| Variable | Description |
64-
| --------------------------------- | ---------------------------------------------------- |
65-
| `COPILOT_OTEL_FILE_EXPORTER_PATH` | Explicit Copilot OpenTelemetry JSONL file to include |
66-
| `LOG_LEVEL` | Adjust verbosity (0 silent ... 5 trace) |
84+
| Variable | Description |
85+
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
86+
| `COPILOT_CONFIG_DIR` | Override the base Copilot directory (default: `~/.copilot`). Both `session-state/` and `otel/` are discovered underneath it. |
87+
| `COPILOT_OTEL_FILE_EXPORTER_PATH` | Add a single explicit OpenTelemetry `.jsonl` file as an additional source (mirrors what the Copilot CLI itself reads when set). |
88+
| `COPILOT_OTEL_DEDUP` | Coexistence policy when both sources contain entries. `loose` (default) — match by session id. `strict` — drop OTel whenever any session-state shutdown is loaded. `off` — disable the dedup step entirely. |
89+
| `COPILOT_PREFER_OTEL` | When set (non-empty / non-zero / not `false`), invert the coexistence rule so OTel wins for any session that appears in both sources. |
90+
| `LOG_LEVEL` | Adjust verbosity (0 silent ... 5 trace) |
6791

6892
## Troubleshooting
6993

7094
::: details No Copilot usage data found
71-
Ensure OpenTelemetry file export is enabled and the exporter path points to an existing `.jsonl` file, or place exported `.jsonl` files under `~/.copilot/otel/`.
95+
The Copilot CLI writes per-session events to `~/.copilot/session-state/<sessionId>/events.jsonl` automatically. If `ccusage copilot daily` still reports no data, verify that the directory exists and that at least one of the per-session subdirectories contains an `events.jsonl` with a `session.shutdown` event (resumed sessions only produce shutdown rows on graceful exit).
96+
97+
If you have configured `COPILOT_CONFIG_DIR`, make sure it points at the directory that contains `session-state/`. As a fallback, OpenTelemetry file export still works — see the env-var block above.
98+
:::
7299

73-
If you are using `copilot --resume`, set the OpenTelemetry environment variables before running the resume command. Earlier activity from sessions started without file export cannot be recovered by ccusage.
100+
::: details Inflated totals when OTel export is also enabled
101+
If you have both `~/.copilot/otel/*.jsonl` files and `~/.copilot/session-state/<uuid>/events.jsonl` files for the same Copilot sessions, the same usage may be counted twice. Set `COPILOT_OTEL_DEDUP=strict` to drop the OTel entries whenever a session-state shutdown is present, or unset `COPILOT_OTEL_FILE_EXPORTER_PATH` and remove the `otel/` directory to skip the OTel path entirely.
74102
:::
75103

76104
::: details Costs showing as $0.00
77-
If a model is not in LiteLLM's database, the cost will be $0.00. [Open an issue](https://github.com/ryoppippi/ccusage/issues/new) to request alias support.
105+
If a model is not in LiteLLM's database — including newer Copilot model variants — the cost will be $0.00. [Open an issue](https://github.com/ryoppippi/ccusage/issues/new) to request alias support.
78106
:::

‎docs/guide/environment-variables.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,10 @@ ccusage detects supported data source files from conventional locations by defau
2121
| `KILO_DATA_DIR` | Kilo | `~/.local/share/kilo` |
2222
| `KIMI_DATA_DIR` | Kimi | `~/.kimi` |
2323
| `QWEN_DATA_DIR` | Qwen | `~/.qwen` |
24-
| `COPILOT_OTEL_FILE_EXPORTER_PATH` | Copilot CLI | Explicit `.jsonl` file |
24+
| `COPILOT_CONFIG_DIR` | Copilot CLI | `~/.copilot` (base dir; reads `session-state/<sessionId>/events.jsonl` and `otel/*.jsonl` underneath) |
25+
| `COPILOT_OTEL_FILE_EXPORTER_PATH` | Copilot CLI | Explicit OpenTelemetry `.jsonl` file (added on top of the base dir) |
26+
| `COPILOT_OTEL_DEDUP` | Copilot CLI | `loose` (default) / `strict` / `off` — coexistence policy when both OTel and session-state contain entries |
27+
| `COPILOT_PREFER_OTEL` | Copilot CLI | Set (non-empty / non-zero / not `false`) to make OTel win for any session that appears in both sources |
2528
| `GEMINI_DATA_DIR` | Gemini CLI | `~/.gemini/tmp` |
2629

2730
Example:
@@ -39,6 +42,7 @@ export OPENCLAW_DIR="/path/to/openclaw,/archive/openclaw"
3942
export KILO_DATA_DIR="/path/to/kilo,/archive/kilo"
4043
export KIMI_DATA_DIR="/path/to/kimi,/archive/kimi"
4144
export QWEN_DATA_DIR="/path/to/qwen,/archive/qwen"
45+
export COPILOT_CONFIG_DIR="/path/to/copilot"
4246
export COPILOT_OTEL_FILE_EXPORTER_PATH="/path/to/copilot-otel.jsonl"
4347
export GEMINI_DATA_DIR="/path/to/gemini/tmp,/archive/gemini/tmp"
4448
ccusage daily

‎docs/guide/getting-started.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -175,7 +175,7 @@ If ccusage shows no data, check:
175175
- Kimi: `${KIMI_DATA_DIR:-~/.kimi}`
176176
- OpenClaw: `${OPENCLAW_DIR:-~/.openclaw}` (also scans `~/.clawdbot`, `~/.moltbot`, `~/.moldbot`)
177177
- Qwen: `${QWEN_DATA_DIR:-~/.qwen}`
178-
- GitHub Copilot CLI: `~/.copilot/otel/*.jsonl` or `COPILOT_OTEL_FILE_EXPORTER_PATH`
178+
- GitHub Copilot CLI: `${COPILOT_CONFIG_DIR:-~/.copilot}/session-state/<sessionId>/events.jsonl` (default; written by the CLI on every install) or `${COPILOT_CONFIG_DIR:-~/.copilot}/otel/*.jsonl` / `COPILOT_OTEL_FILE_EXPORTER_PATH` for OpenTelemetry exports
179179

180180
### Custom Data Directory
181181

@@ -195,6 +195,7 @@ export OPENCLAW_DIR="/path/to/openclaw"
195195
export KILO_DATA_DIR="/path/to/kilo"
196196
export KIMI_DATA_DIR="/path/to/kimi"
197197
export QWEN_DATA_DIR="/path/to/qwen"
198+
export COPILOT_CONFIG_DIR="/path/to/copilot"
198199
export COPILOT_OTEL_FILE_EXPORTER_PATH="/path/to/copilot-otel.jsonl"
199200
```
200201

‎docs/guide/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ ccusage reads from local coding CLI data directories:
8787
| Kilo | `kilo` | `${KILO_DATA_DIR:-~/.local/share/kilo}` |
8888
| Kimi | `kimi` | `${KIMI_DATA_DIR:-~/.kimi}` |
8989
| Qwen | `qwen` | `${QWEN_DATA_DIR:-~/.qwen}` |
90-
| Copilot CLI | `copilot` | `~/.copilot/otel/*.jsonl` |
90+
| Copilot CLI | `copilot` | `${COPILOT_CONFIG_DIR:-~/.copilot}/session-state/<sessionId>/events.jsonl` (default) and `${COPILOT_CONFIG_DIR:-~/.copilot}/otel/*.jsonl` |
9191
| Gemini CLI | `gemini` | `${GEMINI_DATA_DIR:-~/.gemini/tmp}` |
9292

9393
The tool automatically detects available data and aggregates all supported coding CLIs by default.

0 commit comments

Comments
 (0)