You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 8841f92
Browse filesBrowse the repository at this point in the historyBrowse files
* feat(copilot): read session-state usage events
Read session.shutdown model metrics from Copilot session-state files alongside OTel, including cache bucket normalization and canonical model identities for pricing and source deduplication. Support COPILOT_HOME, session-aware monthly and session output with snapshots, and documented source discovery while preserving malformed-line handling and OTel fallback behavior.
* fix(copilot): reconcile cumulative session usage
Keep only the latest session-state shutdown usage for each canonical session/model pair before suppressing matching OTel records. Normalize both Copilot 1m suffix spellings so pricing and source selection share identity.
Replace manually built report snapshots with sanitized fixture-backed focused and unified CLI stdout snapshots, remove the stale terminal test seam, and correct the reasoning-token documentation.
Co-authored-by: Joel Tony <[email protected]>
* fix(copilot): retain post-shutdown OTel usage
Keep matching OTel records emitted after the latest cumulative session-state shutdown so resumed sessions are not undercounted. Suppress records at or before the shutdown timestamp and cover both boundaries in the focused loader regression test.
Co-authored-by: Joel Tony <[email protected]>
* docs(copilot): clarify post-shutdown OTel filtering
Document the timestamp boundary for matching OpenTelemetry rows. Rows at or before the latest canonical shutdown are suppressed, while rows emitted after shutdown by a resumed session remain included.
Co-authored-by: Joel Tony <[email protected]>
* fix(copilot): reconcile ranged session usage
Select cumulative shutdown snapshots as of --until and subtract the preceding snapshot for --since, while keeping resumed OTEL rows and duplicate-event dedupe intact. Include OTEL totals that prove separate reasoning tokens in billed and report totals and map session-state request counts above one to messageCount. Add range, request-count, reasoning, and resumed-session regressions with refreshed Copilot fixtures and snapshots.
Co-authored-by: Joel Tony <[email protected]>
* docs(copilot): document recursive OTel sources
Document recursive discovery under the Copilot OTel directory while retaining the session-state glob and single-file exporter wording. Describe the range-aware cumulative snapshot behavior and the distinction between folded session-state reasoning and separately evidenced OTEL reasoning.
Co-authored-by: Joel Tony <[email protected]>
* docs(copilot): clarify session-state usage fields
Document that session-state reports read requests.count for messageCount while ignoring requests.cost. Add focused daily JSON and table snapshots to cover the parser output alongside the existing monthly and session coverage.
Co-authored-by: Joel Tony <[email protected]>
* fix(copilot): count retained OTel usage rows
Count each emitted OpenTelemetry usage row as one message while retaining the existing session-state requests.count greater-than-one gate. Keep cumulative range subtraction and post-shutdown filtering unchanged so resumed OTel rows add only usage not covered by the canonical shutdown snapshot.
Co-authored-by: Joel Tony <[email protected]>
* test(copilot): refresh monthly and session table snapshots
Refresh the focused and unified Copilot monthly/session table snapshots for the current terminal table formatting.
Co-authored-by: Joel Tony <[email protected]>
* test(zcode): refresh session table snapshot
Refresh the ZCode session table snapshot for the current terminal table formatting.
Co-authored-by: Joel Tony <[email protected]>
---------
Co-authored-by: Joel Tony <[email protected]>
Copy file name to clipboardExpand all lines: docs/guide/copilot/index.md
+24-12Lines changed: 24 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,8 @@
1
1
# GitHub Copilot CLI Data Source (Beta)
2
2
3
-
> GitHub Copilot CLI support is experimental. The adapter reads local OpenTelemetry JSONL files only.
3
+
> GitHub Copilot CLI support is experimental. The adapter reads local session-state and OpenTelemetry JSONL files.
4
4
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 can read GitHub Copilot CLI session-state and OpenTelemetry files as 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.
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 CLI reads Copilot session-state shutdown events from `${COPILOT_HOME:-~/.copilot}/session-state/*/events.jsonl` by default. It also reads OpenTelemetry JSONL files recursively from `${COPILOT_HOME:-~/.copilot}/otel/**/*.jsonl` and includes the single explicit file pointed to by `COPILOT_OTEL_FILE_EXPORTER_PATH`. Set `COPILOT_HOME` to the Copilot data root when the default `~/.copilot` directory has been relocated.
28
28
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
+
Session-state files do not require OpenTelemetry configuration. Shutdown usage is cumulative per canonical session/model pair, so only the latest shutdown is retained. For date-bounded reports, ccusage selects the latest snapshot visible through `--until` and subtracts the latest earlier snapshot before `--since` when one exists. When both sources contain the same session/model pair, the session-state usage is used and matching OpenTelemetry rows are suppressed only when their timestamps are at or before the latest canonical shutdown timestamp for that pair; rows emitted after that timestamp by a resumed session are retained. OpenTelemetry rows for other session/model pairs remain available.
30
+
31
+
For session-state, only `session.shutdown` events are used. For each `data.modelMetrics.<model>` entry, ccusage reads its `usage` fields and, when greater than one, `requests.count` for `messageCount`; each retained OpenTelemetry usage row contributes one message. `requests.cost` is ignored and costs continue to use ccusage's normal token pricing. In session-state data, `inputTokens` includes both cache buckets, so ccusage derives uncached input as `max(inputTokens - cacheReadTokens - cacheWriteTokens, 0)` before populating `inputTokens`; cache reads and cache writes are then reported separately. `reasoningTokens` is a subset of `outputTokens`, so it is not added again to output, total tokens, or cost. Copilot model IDs with `-1m` or `-1m-internal` suffixes, such as `claude-opus-4.6-1m`, are normalized to their priced model name for pricing and source deduplication.
32
+
33
+
For example, a `claude-opus-4.7` shutdown with `inputTokens=100`, `outputTokens=50`, `cacheReadTokens=10`, and `cacheWriteTokens=20` is reported as 70 input tokens, 50 output tokens, 20 cache-creation tokens, and 10 cache-read tokens. With the embedded Opus pricing, its calculated cost is exactly `$0.00173`.
34
+
35
+
Enable these variables before starting or resuming a Copilot CLI session when you want OTel data. Sessions that ran without OpenTelemetry file export remain readable from their session-state files.
@@ -53,24 +63,26 @@ These views support `--json` for structured output, `--compact` for narrow termi
53
63
54
64
## What Gets Calculated
55
65
56
-
-**Token usage** - chat spans are preferred, with inference logs and agent-turn logs used as fallbacks.
66
+
-**Token usage** - the latest cumulative session shutdown usage is read from session-state files; OTel chat spans are preferred within the OTel source, with inference logs and agent-turn logs used as fallbacks.
57
67
-**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.
68
+
-**Input tokens** - session-state `inputTokens` is normalized to uncached input after subtracting cache reads and cache writes.
69
+
-**Reasoning tokens** - session-state reasoning tokens are already included in output tokens; OpenTelemetry reasoning is included when total usage metadata shows it is separate.
70
+
-**Pricing** - costs are calculated from LiteLLM pricing data using the normalized model name; both `-1m` and `-1m-internal` suffixes are removed.
Ensure OpenTelemetry file export is enabled and the exporter path points to an existing `.jsonl` file, or place exported `.jsonl` files under `~/.copilot/otel/`.
83
+
Ensure Copilot session-state files exist under `${COPILOT_HOME:-~/.copilot}/session-state/<session-id>/events.jsonl`, or enable OpenTelemetry file export and place exported `.jsonl` files under `${COPILOT_HOME:-~/.copilot}/otel/`.
72
84
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.
85
+
If you are using `copilot --resume`, session-state events remain available without OpenTelemetry. OTel-only activity from sessions started without file export cannot be recovered by ccusage.
Copy file name to clipboardExpand all lines: docs/guide/environment-variables.md
+3-1Lines changed: 3 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ ccusage supports several environment variables for configuration and customizati
4
4
5
5
## Agent Data Directories
6
6
7
-
ccusage detects supported data source files from conventional locations by default. Set these variables when your data lives somewhere else. Directory variables can be one directory or a comma-separated list of directories; the Copilot variable points at one explicit JSONL export file, and `GROK_HOME` accepts a single root only:
7
+
ccusage detects supported data source files from conventional locations by default. Set these variables when your data lives somewhere else. Directory variables can be one directory or a comma-separated list of directories; `COPILOT_HOME` and `GROK_HOME` accept a single root, while `COPILOT_OTEL_FILE_EXPORTER_PATH` points at one explicit JSONL export file:
- GitHub Copilot CLI: `~/.copilot/otel/*.jsonl` or `COPILOT_OTEL_FILE_EXPORTER_PATH`
179
+
- GitHub Copilot CLI: `${COPILOT_HOME:-~/.copilot}/session-state/*/events.jsonl`, `${COPILOT_HOME:-~/.copilot}/otel/**/*.jsonl`, or the single file specified by`COPILOT_OTEL_FILE_EXPORTER_PATH`
180
180
- Antigravity: `${ANTIGRAVITY_DATA_DIR:-~/.gemini/antigravity*}` or `~/.config/antigravity`
Directory variables can contain comma-separated directories. `COPILOT_OTEL_FILE_EXPORTER_PATH` points to one JSONL file, `GROK_HOME` accepts one root, and `ZCODE_HOME` supports multiple roots and deduplicates them:
209
+
Directory variables can contain comma-separated directories, except `COPILOT_HOME` and `GROK_HOME`, which take a single root. `COPILOT_OTEL_FILE_EXPORTER_PATH` points to one JSONL file, and `ZCODE_HOME` supports multiple roots and deduplicates them:
| Antigravity |`antigravity`|`${ANTIGRAVITY_DATA_DIR:-~/.gemini/antigravity*}` or `~/.config/antigravity`|
93
+
| Grok Build CLI |`grok`|`${GROK_HOME:-~/.grok}`|
94
+
| ZCode |`zcode`|`${ZCODE_HOME:-~/.zcode}`|
95
95
96
96
For OpenCode, `${XDG_DATA_HOME:-$HOME/.local/share}/opencode` is the default-path fallback. When set, `OPENCODE_DATA_DIR` overrides that path; an explicitly empty value disables fallback discovery.
"No GitHub Copilot CLI usage data found.\nEnable Copilot OpenTelemetry file export before starting or resuming Copilot sessions.\nSee https://ccusage.com/guide/copilot/#data-source"
54
+
"No GitHub Copilot CLI usage data found.\nSession-state events are read from ${COPILOT_HOME:-~/.copilot}/session-state/<session-id>/events.jsonl; OpenTelemetry file export remains supported.\nSee https://ccusage.com/guide/copilot/#data-source"
0 commit comments