Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

fix(exporter): read Gemini CLI token usage with Gemini's own count semantics

Claude1e2f7d71ae8c
diff --git a/cli/beacon/internal/tokens/coverage.go b/cli/beacon/internal/tokens/coverage.go
index f64475cb..5c1ad107 100644
--- a/cli/beacon/internal/tokens/coverage.go
+++ b/cli/beacon/internal/tokens/coverage.go
@@ -86,8 +86,12 @@ var usageExpectation = map[string]struct {
"deepseek_harness": {ExpectReported, "native session backfill reports usage when DeepSeek persists it"},
"copilot_cli": {ExpectReported, "session store carries output tokens and cumulative model usage"},
"asymptote_observe": {ExpectReported, "SDK spans carry semconv usage"},
+ // Read from Gemini CLI's own gemini_cli.api_response log, which it emits for every model
+ // response whenever its telemetry is on -- not from the semconv names -- so a Gemini session
+ // with events and no usage is a fault worth reporting. The record shape is pinned from Gemini
+ // CLI's telemetry source rather than from a recorded session.
+ "gemini_cli": {ExpectReported, "api_response log reports input, cache, thought and tool tokens; Gemini CLI emits no cost"},
- "gemini_cli": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
"vscode_copilot": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
"factory": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
"factory_droid": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
diff --git a/cli/beacon/internal/tokens/coverage_test.go b/cli/beacon/internal/tokens/coverage_test.go
index 58eb9a3d..32fc3475 100644
--- a/cli/beacon/internal/tokens/coverage_test.go
+++ b/cli/beacon/internal/tokens/coverage_test.go
@@ -268,6 +268,14 @@ func TestNewHarnessesAreClassifiedNotAlerted(t *testing.T) {
t.Errorf("kimi_code = %+v, want not_instrumented/none -- no Kimi Code hook payload carries token counts", kimi)
}
+ // Gemini CLI writes a gemini_cli.api_response record with its counts for every model response
+ // whenever its telemetry is on, so a Gemini session with events and no usage is the case worth
+ // flagging rather than a runtime spelling its attributes some other way.
+ gemini := lineFor(t, Coverage([]schema.Event{plainEvent("gemini_cli")}, []string{"gemini_cli"}), "gemini_cli")
+ if gemini.Status != CoverageSilent || gemini.Expectation != ExpectReported {
+ t.Errorf("gemini_cli = %+v, want silent/reported -- usage is read from Gemini's own api_response log", gemini)
+ }
+
grokBot := lineFor(t, Coverage([]schema.Event{plainEvent("grok_bot")}, nil), "grok_bot")
if grokBot.Expectation != ExpectGenericOTLP {
t.Errorf("grok_bot expectation = %q, want generic_otlp -- it arrives only via Cursor's OTel export", grokBot.Expectation)
diff --git a/cli/beacon/internal/tokens/tokens_test.go b/cli/beacon/internal/tokens/tokens_test.go
index 5012eaf9..aaefe9a2 100644
--- a/cli/beacon/internal/tokens/tokens_test.go
+++ b/cli/beacon/internal/tokens/tokens_test.go
@@ -212,6 +212,67 @@ func TestAggregateDedupesDualChannelUsage(t *testing.T) {
}
}
+// Gemini CLI reports each response on the gemini_cli.api_response log and again on the
+// cumulative gemini_cli.token.usage counter, and puts its session.id on both, so the two land in
+// one (harness, session) scope and the log channel wins. The events are shaped as the exporter
+// writes them: the log already carries the disjoint reading (input = prompt - cached + tool,
+// output = candidates + thoughts), and so does each metric line.
+func TestAggregateCountsGeminiLogAndMetricChannelsOnce(t *testing.T) {
+ const session = "8c4f0d2e-5b1a-4e7c-9f3d-2a6b8e1c7d40"
+ response := func(ts string, input, output, cacheRead, reasoning int64) schema.Event {
+ return usageEventFixture(ts, "gemini_cli", session, "gemini-2.5-pro", func(e *schema.Event) {
+ e.Event.Action = "tool.invoked"
+ e.Event.Category = "tool"
+ e.Message = "API response from gemini-2.5-pro. Status: 200. Duration: 2311ms."
+ e.GenAI.Usage.InputTokens = int64Ptr(input)
+ e.GenAI.Usage.OutputTokens = int64Ptr(output)
+ e.GenAI.Usage.CacheRead = &schema.GenAIUsageCacheReadInfo{InputTokens: int64Ptr(cacheRead)}
+ e.GenAI.Usage.Reasoning = &schema.GenAIUsageReasoningInfo{OutputTokens: int64Ptr(reasoning)}
+ })
+ }
+ counter := func(ts, tokenType string, mutate func(*schema.GenAIUsageInfo)) schema.Event {
+ return usageEventFixture(ts, "gemini_cli", session, "gemini-2.5-pro", func(e *schema.Event) {
+ e.Message = "gemini_cli.token.usage"
+ e.GenAI.Token = &schema.GenAITokenInfo{Type: tokenType}
+ mutate(e.GenAI.Usage)
+ e.Raw = map[string]interface{}{"metric_name": "gemini_cli.token.usage", "metric_temporality": "Cumulative"}
+ })
+ }
+ collection := func(ts string, input, output, cacheRead, reasoning int64) []schema.Event {
+ return []schema.Event{
+ counter(ts, "input", func(u *schema.GenAIUsageInfo) { u.InputTokens = int64Ptr(input) }),
+ counter(ts, "output", func(u *schema.GenAIUsageInfo) { u.OutputTokens = int64Ptr(output) }),
+ counter(ts, "cache", func(u *schema.GenAIUsageInfo) {
+ u.CacheRead = &schema.GenAIUsageCacheReadInfo{InputTokens: int64Ptr(cacheRead)}
+ }),
+ counter(ts, "thought", func(u *schema.GenAIUsageInfo) {
+ u.Reasoning = &schema.GenAIUsageReasoningInfo{OutputTokens: int64Ptr(reasoning)}
+ }),
+ counter(ts, "tool", func(u *schema.GenAIUsageInfo) {}),
+ }
+ }
+ events := []schema.Event{
+ // prompt 12000 (8000 cached), candidates 350, thoughts 420: total 12770.
+ response("2026-10-05T09:30:00Z", 4000, 770, 8000, 420),
+ // prompt 5000, tool-use prompt 600, candidates 100: total 5700.
+ response("2026-10-05T09:30:40Z", 5600, 100, 0, 0),
+ }
+ events = append(events, collection("2026-10-05T09:31:00Z", 9600, 870, 8000, 420)...)
+ events = append(events, collection("2026-10-05T09:32:00Z", 9600, 870, 8000, 420)...)
+
+ report := Aggregate(events, Options{})
+ got := report.Totals
+ if got.InputTokens != 9600 || got.OutputTokens != 870 || got.CacheReadInputTokens != 8000 || got.ReasoningOutputTokens != 420 {
+ t.Fatalf("totals = %#v, want the log channel once: input 9600, output 870, cache read 8000, reasoning 420", got)
+ }
+ if got.TotalTokens() != 12770+5700 {
+ t.Fatalf("total tokens = %d, want Gemini's own totals 12770 + 5700", got.TotalTokens())
+ }
+ if got.Events != 2 {
+ t.Fatalf("events = %d, want the two api_response lines only", got.Events)
+ }
+}
+
func TestAggregatePrefersCodexTurnSpansAfterCutover(t *testing.T) {
codexMetric := func(ts string, input int64) schema.Event {
return usageEventFixture(ts, "codex_cli", "", "gpt-5.6-sol", func(e *schema.Event) {
diff --git a/collector-builder/exporter/beaconjsonexporter/README.md b/collector-builder/exporter/beaconjsonexporter/README.md
index 868a1766..466145ba 100644
--- a/collector-builder/exporter/beaconjsonexporter/README.md
+++ b/collector-builder/exporter/beaconjsonexporter/README.md
@@ -38,6 +38,13 @@ Token and cost usage:
`cacheCreation`, `reasoning`); cost datapoints map to
`gen_ai.usage.cost_usd`. Unknown token types keep the raw value in
`raw.metric_value` only.
+- Gemini CLI's counts overlap differently: its input includes the cache and its
+ output excludes thinking tokens. The `gemini_cli.api_response` log record and
+ the `gemini_cli.token.usage` series (`input`, `output`, `thought`, `cache`,
+ `tool`) both map to input = prompt - cached + tool-use prompt, cache read =
+ cached, output = candidates + thoughts, and reasoning = thoughts. The
+ `gen_ai.client.inference.operation.details` record that restates the same
+ response carries no usage, so a response is counted once.
- Datapoint events use the datapoint timestamp and record
`raw.metric_temporality`, `raw.metric_monotonic`, `raw.metric_value`, and
(for histograms) `raw.metric_count` so downstream aggregation can dedupe
diff --git a/collector-builder/exporter/beaconjsonexporter/gemini_usage_e2e_test.go b/collector-builder/exporter/beaconjsonexporter/gemini_usage_e2e_test.go
new file mode 100644
index 00000000..9f16684f
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/gemini_usage_e2e_test.go
@@ -0,0 +1,166 @@
+package beaconjsonexporter
+
+import (
+ "bufio"
+ "context"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "testing"
+ "time"
+
+ "go.opentelemetry.io/collector/exporter"
+ "go.opentelemetry.io/collector/pdata/pcommon"
+ "go.opentelemetry.io/collector/pdata/plog"
+ "go.opentelemetry.io/collector/pdata/pmetric"
+)
+
+// One Gemini CLI response, exported the way Gemini CLI's logApiResponse exports it: the native
+// gemini_cli.api_response record, its gen_ai.client.inference.operation.details restatement, and
+// the gemini_cli.token.usage counter series it records for the same usageMetadata
+// (promptTokenCount 12000 of which cachedContentTokenCount 8000, candidatesTokenCount 350,
+// thoughtsTokenCount 420, toolUsePromptTokenCount 0, totalTokenCount 12770).
+//
+// Every line the exporter writes must carry Beacon's disjoint reading, with exactly one log line
+// holding the response's usage. The metric lines carry the same usage again under a metric_name,
+// which is what the token report's log-over-metric dedupe keys on.
+func TestConsumeGeminiAPIResponseWritesDisjointUsageOnce(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ exp, err := newExporter(&Config{
+ Path: path,
+ MaxEventBytes: defaultMaxEventBytes,
+ RotateBytes: defaultRotateBytes,
+ RedactSecrets: true,
+ }, exporter.Settings{})
+ if err != nil {
+ t.Fatalf("newExporter returned error: %v", err)
+ }
+ ts := time.Date(2026, 10, 5, 9, 30, 0, 0, time.UTC)
+ common := func(attrs pcommon.Map) {
+ attrs.PutStr("session.id", "8c4f0d2e-5b1a-4e7c-9f3d-2a6b8e1c7d40")
+ attrs.PutStr("installation.id", "6f1e2b4c-0d3a-4e5f-9a8b-7c6d5e4f3a2b")
+ attrs.PutBool("interactive", true)
+ attrs.PutStr("auth_type", "oauth-personal")
+ }
+
+ logs := plog.NewLogs()
+ rl := logs.ResourceLogs().AppendEmpty()
+ rl.Resource().Attributes().PutStr("service.name", "gemini-cli")
+ rl.Resource().Attributes().PutStr("service.version", "0.9.0")
+ records := rl.ScopeLogs().AppendEmpty().LogRecords()
+ native := records.AppendEmpty()
+ native.SetTimestamp(pcommon.NewTimestampFromTime(ts))
+ native.Body().SetStr("API response from gemini-2.5-pro. Status: 200. Duration: 2311ms.")
+ common(native.Attributes())
+ native.Attributes().PutStr("event.name", "gemini_cli.api_response")
+ native.Attributes().PutStr("event.timestamp", ts.Format(time.RFC3339Nano))
+ native.Attributes().PutStr("model", "gemini-2.5-pro")
+ native.Attributes().PutInt("duration_ms", 2311)
+ native.Attributes().PutInt("input_token_count", 12000)
+ native.Attributes().PutInt("output_token_count", 350)
+ native.Attributes().PutInt("cached_content_token_count", 8000)
+ native.Attributes().PutInt("thoughts_token_count", 420)
+ native.Attributes().PutInt("tool_token_count", 0)
+ native.Attributes().PutInt("total_token_count", 12770)
+ native.Attributes().PutStr("prompt_id", "8c4f0d2e########1")
+ native.Attributes().PutInt("status_code", 200)
+ semantic := records.AppendEmpty()
+ semantic.SetTimestamp(pcommon.NewTimestampFromTime(ts))
+ semantic.Body().SetStr("GenAI operation details from gemini-2.5-pro. Status: 200. Duration: 2311ms.")
+ common(semantic.Attributes())
+ semantic.Attributes().PutStr("event.name", "gen_ai.client.inference.operation.details")
+ semantic.Attributes().PutStr("gen_ai.operation.name", "generate_content")
+ semantic.Attributes().PutStr("gen_ai.provider.name", "gcp.vertex_ai")
+ semantic.Attributes().PutStr("gen_ai.request.model", "gemini-2.5-pro")
+ semantic.Attributes().PutStr("gen_ai.response.model", "gemini-2.5-pro")
+ semantic.Attributes().PutInt("gen_ai.usage.input_tokens", 12000)
+ semantic.Attributes().PutInt("gen_ai.usage.output_tokens", 350)
+
+ metrics := pmetric.NewMetrics()
+ rm := metrics.ResourceMetrics().AppendEmpty()
+ rm.Resource().Attributes().PutStr("service.name", "gemini-cli")
+ rm.Resource().Attributes().PutStr("service.version", "0.9.0")
+ metric := rm.ScopeMetrics().AppendEmpty().Metrics().AppendEmpty()
+ metric.SetName("gemini_cli.token.usage")
+ sum := metric.SetEmptySum()
+ sum.SetAggregationTemporality(pmetric.AggregationTemporalityCumulative)
+ sum.SetIsMonotonic(true)
+ for _, point := range []struct {
+ tokenType string
+ value int64
+ }{{"input", 12000}, {"output", 350}, {"cache", 8000}, {"thought", 420}, {"tool", 0}} {
+ dp := sum.DataPoints().AppendEmpty()
+ dp.SetTimestamp(pcommon.NewTimestampFromTime(ts.Add(time.Minute)))
+ dp.SetIntValue(point.value)
+ common(dp.Attributes())
+ dp.Attributes().PutStr("model", "gemini-2.5-pro")
+ dp.Attributes().PutStr("type", point.tokenType)
+ }
+
+ if err := exp.consumeLogs(context.Background(), logs); err != nil {
+ t.Fatalf("consumeLogs returned error: %v", err)
+ }
+ if err := exp.consumeMetrics(context.Background(), metrics); err != nil {
+ t.Fatalf("consumeMetrics returned error: %v", err)
+ }
+
+ file, err := os.Open(path)
+ if err != nil {
+ t.Fatalf("open runtime log: %v", err)
+ }
+ defer file.Close()
+ type totals struct{ input, output, cacheRead, reasoning, lines int64 }
+ var logTotals, metricTotals totals
+ scanner := bufio.NewScanner(file)
+ scanner.Buffer(make([]byte, 0, 1<<20), 1<<20)
+ for scanner.Scan() {
+ var event beaconEvent
+ if err := json.Unmarshal(scanner.Bytes(), &event); err != nil {
+ t.Fatalf("unmarshal line: %v", err)
+ }
+ if event.Harness.Name != "gemini_cli" || event.Session == nil || event.Session.ID != "8c4f0d2e-5b1a-4e7c-9f3d-2a6b8e1c7d40" {
+ t.Fatalf("line harness/session = %q/%#v, want gemini_cli and the Gemini session id on every channel", event.Harness.Name, event.Session)
+ }
+ if event.GenAI == nil || event.GenAI.Usage == nil {
+ continue
+ }
+ target := &logTotals
+ if name, _ := event.Raw["metric_name"].(string); name != "" {
+ target = &metricTotals
+ }
+ u := event.GenAI.Usage
+ if u.InputTokens != nil {
+ target.input += *u.InputTokens
+ }
+ if u.OutputTokens != nil {
+ target.output += *u.OutputTokens
+ }
+ if u.CacheRead != nil && u.CacheRead.InputTokens != nil {
+ target.cacheRead += *u.CacheRead.InputTokens
+ }
+ if u.Reasoning != nil && u.Reasoning.OutputTokens != nil {
+ target.reasoning += *u.Reasoning.OutputTokens
+ }
+ if u.CacheCreation != nil {
+ t.Fatalf("cache_creation = %#v, want none: Gemini reports no cache writes", u.CacheCreation)
+ }
+ target.lines++
+ }
+ if err := scanner.Err(); err != nil {
+ t.Fatalf("scan runtime log: %v", err)
+ }
+ want := totals{input: 4000, output: 770, cacheRead: 8000, reasoning: 420}
+ gotLog := logTotals
+ gotLog.lines = 0
+ if gotLog != want || logTotals.lines != 1 {
+ t.Fatalf("log channel = %+v over %d lines, want %+v on exactly one line", gotLog, logTotals.lines, want)
+ }
+ if logTotals.input+logTotals.output+logTotals.cacheRead != 12770 {
+ t.Fatalf("log channel total = %d, want Gemini's total_token_count 12770", logTotals.input+logTotals.output+logTotals.cacheRead)
+ }
+ gotMetric := metricTotals
+ gotMetric.lines = 0
+ if gotMetric != want {
+ t.Fatalf("metric channel = %+v, want the same disjoint reading %+v", gotMetric, want)
+ }
+}
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
index 7af807ef..9d48ca7b 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
@@ -329,6 +329,7 @@ func (c Converter) EventFromLog(resourceAttrs map[string]interface{}, record plo
})
c.NormalizeCodexLogEvent(&event, attrs)
c.NormalizeClaudeLogEvent(&event, attrs, body)
+ NormalizeGeminiLogEvent(&event, attrs)
// Last, so it sees the action and category the normalizers settled on rather
// than the ones InferAction guessed.
c.PromoteRetainedContent(&event, attrs, body)
@@ -951,9 +952,16 @@ func (c Converter) eventsFromUsageMetric(resourceAttrs map[string]interface{}, m
"metric_temporality": sum.AggregationTemporality().String(),
"metric_monotonic": sum.IsMonotonic(),
}
+ // Gemini CLI's input series includes its cache series and its output series
+ // leaves out its thought series; see gemini_usage.go. Nil for every other metric.
+ geminiSeries := geminiTokenSeriesByScope(metric)
for i := 0; i < sum.DataPoints().Len(); i++ {
dp := sum.DataPoints().At(i)
- events = append(events, c.usageEventFromDataPoint(resourceAttrs, metric, dp.Attributes(), dp.Timestamp(), adjustValue(dp.Attributes(), dp.Timestamp(), numberDataPointValue(dp)), extra))
+ event := c.usageEventFromDataPoint(resourceAttrs, metric, dp.Attributes(), dp.Timestamp(), adjustValue(dp.Attributes(), dp.Timestamp(), numberDataPointValue(dp)), extra)
+ if geminiSeries != nil {
+ geminiSeries.apply(&event, dp.Attributes(), dp.Timestamp(), numberDataPointValue(dp))
+ }
+ events = append(events, event)
}
case pmetric.MetricTypeGauge:
gauge := metric.Gauge()
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/gemini_usage.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/gemini_usage.go
new file mode 100644
index 00000000..5e2dd28e
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/gemini_usage.go
@@ -0,0 +1,193 @@
+package beaconevent
+
+import (
+ "fmt"
+ "math"
+ "sort"
+ "strings"
+
+ "go.opentelemetry.io/collector/pdata/pcommon"
+ "go.opentelemetry.io/collector/pdata/pmetric"
+)
+
+// Gemini CLI token usage.
+//
+// Gemini CLI reports each model response's usageMetadata three ways: the gemini_cli.api_response
+// log record (input_token_count, output_token_count, cached_content_token_count,
+// thoughts_token_count, tool_token_count, total_token_count), the gemini_cli.token.usage counter
+// (one series per type: input, output, thought, cache, tool), and an OTel GenAI restatement --
+// the gen_ai.client.inference.operation.details log record and the gen_ai.client.token.usage
+// histogram -- that carries input and output only.
+//
+// Gemini's counts are not disjoint the way gen_ai.usage is. The API defines promptTokenCount
+// (input_token_count) as including the cached content, so uncached input is prompt minus
+// cachedContentTokenCount. candidatesTokenCount (output_token_count) leaves out
+// thoughtsTokenCount, while Beacon treats reasoning as a breakdown of output, so output is
+// candidates plus thoughts and reasoning is thoughts. toolUsePromptTokenCount is the results of
+// tool executions fed back to the model as input and is not inside promptTokenCount
+// (totalTokenCount is the sum of prompt, candidates, tool-use prompt and thoughts), so it is added
+// to uncached input. With that reading input + output + cache_read equals Gemini's own
+// total_token_count, and nothing is counted twice. Gemini reports no cache writes.
+
+const (
+ geminiAPIResponseEvent = "gemini_cli.api_response"
+ geminiOperationDetailsEvent = "gen_ai.client.inference.operation.details"
+ geminiTokenUsageMetric = "gemini_cli.token.usage"
+ geminiTokenTypeAttribute = "type"
+ geminiHarness = "gemini_cli"
+ geminiTokenTypeInput = "input"
+ geminiTokenTypeOutput = "output"
+ geminiTokenTypeThought = "thought"
+ geminiTokenTypeCache = "cache"
+ geminiTokenTypeToolUsePrompts = "tool"
+)
+
+// NormalizeGeminiLogEvent gives the api_response record the response's usage and takes it off
+// the operation-details record. Gemini CLI emits both records for every response from one call
+// (logApiResponse), and the operation-details one restates only input and output -- with input
+// still including the cache -- so reading usage from both would count every response twice.
+func NormalizeGeminiLogEvent(event *Event, attrs map[string]interface{}) {
+ if event == nil || event.Harness.Name != geminiHarness {
+ return
+ }
+ switch FirstString(attrs, "event.name") {
+ case geminiOperationDetailsEvent:
+ if event.GenAI != nil {
+ event.GenAI.Usage = nil
+ }
+ case geminiAPIResponseEvent:
+ usage := geminiAPIResponseUsage(attrs)
+ if usage == nil {
+ return
+ }
+ if event.GenAI == nil {
+ event.GenAI = &GenAIInfo{}
+ }
+ event.GenAI.Usage = usage
+ }
+}
+
+func geminiAPIResponseUsage(attrs map[string]interface{}) *GenAIUsageInfo {
+ prompt, hasPrompt := Int64Attr(attrs, "input_token_count")
+ candidates, hasCandidates := Int64Attr(attrs, "output_token_count")
+ cached, hasCached := Int64Attr(attrs, "cached_content_token_count")
+ thoughts, hasThoughts := Int64Attr(attrs, "thoughts_token_count")
+ tool, hasTool := Int64Attr(attrs, "tool_token_count")
+ if !hasPrompt && !hasCandidates && !hasCached && !hasThoughts && !hasTool {
+ return nil
+ }
+ nonNegative := func(v int64) int64 {
+ if v < 0 {
+ return 0
+ }
+ return v
+ }
+ prompt, candidates, cached, thoughts, tool = nonNegative(prompt), nonNegative(candidates), nonNegative(cached), nonNegative(thoughts), nonNegative(tool)
+ usage := &GenAIUsageInfo{}
+ if hasPrompt || hasTool {
+ input := nonNegative(prompt-cached) + tool
+ usage.InputTokens = &input
+ }
+ if hasCached {
+ usage.CacheRead = &GenAIUsageCacheReadInfo{InputTokens: &cached}
+ }
+ if hasCandidates || hasThoughts {
+ output := candidates + thoughts
+ usage.OutputTokens = &output
+ }
+ if hasThoughts {
+ usage.Reasoning = &GenAIUsageReasoningInfo{OutputTokens: &thoughts}
+ }
+ return usage
+}
+
+// geminiTokenSeries holds, for one collection of gemini_cli.token.usage, every series' value by
+// its attribute set without the type, so the input and output series can be read alongside the
+// cache, tool and thought series of the same model, session and timestamp.
+type geminiTokenSeries map[string]map[string]float64
+
+func isGeminiTokenUsageMetric(metric pmetric.Metric) bool {
+ return strings.EqualFold(strings.TrimSpace(metric.Name()), geminiTokenUsageMetric) && metric.Type() == pmetric.MetricTypeSum
+}
+
+// geminiTokenSeriesByScope indexes a gemini_cli.token.usage Sum by series scope. Returns nil
+// for every other metric. Gemini CLI's counter is cumulative by default, and a running total of
+// (input - cache + tool) is still a running total of uncached input, so the same per-collection
+// reading holds for cumulative and delta temporality alike.
+func geminiTokenSeriesByScope(metric pmetric.Metric) geminiTokenSeries {
+ if !isGeminiTokenUsageMetric(metric) {
+ return nil
+ }
+ out := geminiTokenSeries{}
+ dps := metric.Sum().DataPoints()
+ for i := 0; i < dps.Len(); i++ {
+ dp := dps.At(i)
+ scope, tokenType := geminiSeriesScope(dp.Attributes(), dp.Timestamp())
+ if out[scope] == nil {
+ out[scope] = map[string]float64{}
+ }
+ out[scope][tokenType] += numberDataPointValue(dp)
+ }
+ return out
+}
+
+// geminiSeriesScope returns the series identity without its type, plus the type. Every attribute
+// is part of the identity, so two sessions or two models in one export never share siblings.
+func geminiSeriesScope(attrs pcommon.Map, ts pcommon.Timestamp) (string, string) {
+ values := AttrsToMap(attrs)
+ tokenType := strings.ToLower(strings.TrimSpace(FirstString(values, geminiTokenTypeAttribute)))
+ keys := make([]string, 0, len(values))
+ for key := range values {
+ if key != geminiTokenTypeAttribute {
+ keys = append(keys, key)
+ }
+ }
+ sort.Strings(keys)
+ var b strings.Builder
+ fmt.Fprintf(&b, "%d", ts.AsTime().UnixNano())
+ for _, key := range keys {
+ fmt.Fprintf(&b, "\x00%s=%v", key, values[key])
+ }
+ return b.String(), tokenType
+}
+
+// apply replaces the usage usageEventFromDataPoint read from one datapoint's own type and value
+// with the Gemini reading of it. The event keeps Gemini's type name in gen_ai.token.type, and
+// raw.metric_value keeps the value as reported.
+func (series geminiTokenSeries) apply(event *Event, attrs pcommon.Map, ts pcommon.Timestamp, value float64) {
+ adjusted, tokenType := series.adjust(attrs, ts, value)
+ if event.GenAI == nil {
+ event.GenAI = &GenAIInfo{}
+ }
+ event.GenAI.Usage = nil
+ event.GenAI.Token = nil
+ ApplyTokenUsage(event, tokenType, int64(math.Round(adjusted)))
+ if original := FirstString(AttrsToMap(attrs), geminiTokenTypeAttribute); original != "" {
+ event.GenAI.Token = &GenAITokenInfo{Type: original}
+ }
+}
+
+// adjust maps one gemini_cli.token.usage datapoint onto Beacon's disjoint usage. It returns the
+// value to record and the token type ApplyTokenUsage should record it as. The tool series keeps
+// its own type, which ApplyTokenUsage leaves unmapped (raw only), because its count is already
+// folded into the input series.
+func (series geminiTokenSeries) adjust(attrs pcommon.Map, ts pcommon.Timestamp, value float64) (float64, string) {
+ scope, tokenType := geminiSeriesScope(attrs, ts)
+ siblings := series[scope]
+ switch tokenType {
+ case geminiTokenTypeInput:
+ uncached := value - siblings[geminiTokenTypeCache]
+ if uncached < 0 {
+ uncached = 0
+ }
+ return uncached + siblings[geminiTokenTypeToolUsePrompts], "input"
+ case geminiTokenTypeOutput:
+ return value + siblings[geminiTokenTypeThought], "output"
+ case geminiTokenTypeThought:
+ return value, "reasoning"
+ case geminiTokenTypeCache:
+ return value, "cacheRead"
+ default:
+ return value, tokenType
+ }
+}
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/gemini_usage_test.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/gemini_usage_test.go
new file mode 100644
index 00000000..3442b96a
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/gemini_usage_test.go
@@ -0,0 +1,390 @@
+package beaconevent
+
+import (
+ "testing"
+ "time"
+
+ "go.opentelemetry.io/collector/pdata/pcommon"
+ "go.opentelemetry.io/collector/pdata/plog"
+ "go.opentelemetry.io/collector/pdata/pmetric"
+)
+
+// geminiAPIResponse is one Gemini usageMetadata as Gemini CLI's ApiResponseEvent copies it onto
+// the gemini_cli.api_response log record: input_token_count is promptTokenCount,
+// output_token_count candidatesTokenCount, cached_content_token_count cachedContentTokenCount,
+// thoughts_token_count thoughtsTokenCount, tool_token_count toolUsePromptTokenCount, and
+// total_token_count totalTokenCount.
+type geminiAPIResponse struct {
+ input, output, cached, thoughts, tool, total int64
+}
+
+// appendGeminiAPIResponseLogs appends the two log records Gemini CLI's logApiResponse emits for
+// one model response: the native gemini_cli.api_response record and the OTel GenAI
+// gen_ai.client.inference.operation.details record that restates its input and output counts.
+func appendGeminiAPIResponseLogs(records plog.LogRecordSlice, sessionID, model string, ts time.Time, usage geminiAPIResponse) {
+ common := func(rec plog.LogRecord) {
+ rec.SetTimestamp(pcommon.NewTimestampFromTime(ts))
+ attrs := rec.Attributes()
+ attrs.PutStr("session.id", sessionID)
+ attrs.PutStr("installation.id", "6f1e2b4c-0d3a-4e5f-9a8b-7c6d5e4f3a2b")
+ attrs.PutBool("interactive", true)
+ attrs.PutStr("auth_type", "oauth-personal")
+ attrs.PutStr("event.timestamp", ts.Format(time.RFC3339Nano))
+ }
+
+ native := records.AppendEmpty()
+ common(native)
+ native.Body().SetStr("API response from " + model + ". Status: 200. Duration: 2311ms.")
+ attrs := native.Attributes()
+ attrs.PutStr("event.name", "gemini_cli.api_response")
+ attrs.PutStr("model", model)
+ attrs.PutInt("duration_ms", 2311)
+ attrs.PutInt("input_token_count", usage.input)
+ attrs.PutInt("output_token_count", usage.output)
+ attrs.PutInt("cached_content_token_count", usage.cached)
+ attrs.PutInt("thoughts_token_count", usage.thoughts)
+ attrs.PutInt("tool_token_count", usage.tool)
+ attrs.PutInt("total_token_count", usage.total)
+ attrs.PutStr("prompt_id", sessionID+"########1")
+ attrs.PutInt("status_code", 200)
+ attrs.PutInt("http.status_code", 200)
+ attrs.PutStr("role", "main")
+ attrs.PutEmptySlice("finish_reasons").AppendEmpty().SetStr("STOP")
+
+ semantic := records.AppendEmpty()
+ common(semantic)
+ semantic.Body().SetStr("GenAI operation details from " + model + ". Status: 200. Duration: 2311ms.")
+ attrs = semantic.Attributes()
+ attrs.PutStr("event.name", "gen_ai.client.inference.operation.details")
+ attrs.PutStr("gen_ai.response.id", "resp-"+sessionID)
+ attrs.PutEmptySlice("gen_ai.response.finish_reasons").AppendEmpty().SetStr("stop")
+ attrs.PutStr("gen_ai.operation.name", "generate_content")
+ attrs.PutStr("gen_ai.provider.name", "gcp.vertex_ai")
+ attrs.PutStr("gen_ai.request.model", model)
+ attrs.PutStr("gen_ai.response.model", model)
+ attrs.PutInt("gen_ai.usage.input_tokens", usage.input)
+ attrs.PutInt("gen_ai.usage.output_tokens", usage.output)
+}
+
+func newGeminiLogs() (plog.Logs, plog.LogRecordSlice) {
+ logs := plog.NewLogs()
+ rl := logs.ResourceLogs().AppendEmpty()
+ rl.Resource().Attributes().PutStr("service.name", "gemini-cli")
+ rl.Resource().Attributes().PutStr("service.version", "0.9.0")
+ return logs, rl.ScopeLogs().AppendEmpty().LogRecords()
+}
+
+func int64Value(p *int64) int64 {
+ if p == nil {
+ return -1
+ }
+ return *p
+}
+
+// Gemini's promptTokenCount already contains cachedContentTokenCount, its candidatesTokenCount
+// leaves out thoughtsTokenCount, and toolUsePromptTokenCount is input that promptTokenCount does
+// not hold (totalTokenCount is prompt + candidates + tool-use prompt + thoughts). Beacon's
+// disjoint usage therefore records input = prompt - cached + tool, output = candidates +
+// thoughts with thoughts as its reasoning breakdown, and cached as cache read, so that
+// input + output + cache_read reproduces Gemini's own total.
+func TestEventsFromLogsMapsGeminiAPIResponseUsage(t *testing.T) {
+ tests := []struct {
+ name string
+ usage geminiAPIResponse
+ input, output, cacheRead, reasoning int64
+ }{
+ {
+ name: "thinking model with a cached prefix",
+ usage: geminiAPIResponse{input: 12000, output: 350, cached: 8000, thoughts: 420, tool: 0, total: 12770},
+ input: 4000, output: 770, cacheRead: 8000, reasoning: 420,
+ },
+ {
+ name: "tool-use prompt tokens are input outside promptTokenCount",
+ usage: geminiAPIResponse{input: 5000, output: 100, cached: 0, thoughts: 0, tool: 600, total: 5700},
+ input: 5600, output: 100, cacheRead: 0, reasoning: 0,
+ },
+ {
+ // Gemini CLI writes 0 for every count a response's usageMetadata omitted.
+ name: "response without usage metadata",
+ usage: geminiAPIResponse{},
+ input: 0, output: 0, cacheRead: 0, reasoning: 0,
+ },
+ }
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ logs, records := newGeminiLogs()
+ appendGeminiAPIResponseLogs(records, "gemini-session-1", "gemini-2.5-pro", time.Unix(1760000000, 0).UTC(), tt.usage)
+
+ events := NewConverter(Options{}).EventsFromLogs(logs)
+ if len(events) != 2 {
+ t.Fatalf("expected 2 events, got %d", len(events))
+ }
+ native, semantic := events[0], events[1]
+ if native.Harness.Name != "gemini_cli" || native.Session == nil || native.Session.ID != "gemini-session-1" {
+ t.Fatalf("native record harness/session = %q/%#v, want gemini_cli/gemini-session-1", native.Harness.Name, native.Session)
+ }
+ if native.GenAI == nil || native.GenAI.Usage == nil {
+ t.Fatalf("api_response record carries no usage: %#v", native.GenAI)
+ }
+ usage := native.GenAI.Usage
+ var cacheRead, reasoning *int64
+ if usage.CacheRead != nil {
+ cacheRead = usage.CacheRead.InputTokens
+ }
+ if usage.Reasoning != nil {
+ reasoning = usage.Reasoning.OutputTokens
+ }
+ if int64Value(usage.InputTokens) != tt.input || int64Value(usage.OutputTokens) != tt.output ||
+ int64Value(cacheRead) != tt.cacheRead || int64Value(reasoning) != tt.reasoning {
+ t.Fatalf("usage = input %d output %d cache_read %d reasoning %d, want %d/%d/%d/%d",
+ int64Value(usage.InputTokens), int64Value(usage.OutputTokens), int64Value(cacheRead), int64Value(reasoning),
+ tt.input, tt.output, tt.cacheRead, tt.reasoning)
+ }
+ if usage.CacheCreation != nil {
+ t.Fatalf("cache_creation = %#v, want none: Gemini reports no cache writes", usage.CacheCreation)
+ }
+ if got := tt.input + tt.output + tt.cacheRead; got != tt.usage.total {
+ t.Fatalf("input + output + cache_read = %d, want Gemini's total_token_count %d", got, tt.usage.total)
+ }
+ if native.Model != "gemini-2.5-pro" {
+ t.Fatalf("model = %q, want gemini-2.5-pro", native.Model)
+ }
+ // The semconv restatement of the same response must not count it a second time.
+ if semantic.GenAI != nil && semantic.GenAI.Usage != nil {
+ t.Fatalf("operation.details record kept usage %#v; it restates the api_response counts", semantic.GenAI.Usage)
+ }
+ })
+ }
+}
+
+// The operation-details record is only a duplicate on Gemini CLI, which always emits it beside
+// api_response. The same event name from any other runtime is that runtime's only usage record.
+func TestEventsFromLogsKeepsOperationDetailsUsageOutsideGemini(t *testing.T) {
+ logs := plog.NewLogs()
+ rl := logs.ResourceLogs().AppendEmpty()
+ rl.Resource().Attributes().PutStr("service.name", "agent-api")
+ rec := rl.ScopeLogs().AppendEmpty().LogRecords().AppendEmpty()
+ rec.Attributes().PutStr("event.name", "gen_ai.client.inference.operation.details")
+ rec.Attributes().PutStr("gen_ai.operation.name", "chat")
+ rec.Attributes().PutInt("gen_ai.usage.input_tokens", 120)
+ rec.Attributes().PutInt("gen_ai.usage.output_tokens", 30)
+
+ events := NewConverter(Options{}).EventsFromLogs(logs)
+ if len(events) != 1 || events[0].GenAI == nil || events[0].GenAI.Usage == nil {
+ t.Fatalf("events = %#v, want one event with usage", events)
+ }
+ if got := int64Value(events[0].GenAI.Usage.InputTokens); got != 120 {
+ t.Fatalf("input_tokens = %d, want 120", got)
+ }
+}
+
+// A non-Gemini record that happens to use the same attribute names is not reinterpreted.
+func TestEventsFromLogsIgnoresGeminiCountNamesOutsideGemini(t *testing.T) {
+ logs := plog.NewLogs()
+ rl := logs.ResourceLogs().AppendEmpty()
+ rl.Resource().Attributes().PutStr("service.name", "agent-api")
+ rec := rl.ScopeLogs().AppendEmpty().LogRecords().AppendEmpty()
+ rec.Attributes().PutStr("event.name", "gemini_cli.api_response")
+ rec.Attributes().PutInt("input_token_count", 100)
+
+ events := NewConverter(Options{}).EventsFromLogs(logs)
+ if len(events) != 1 {
+ t.Fatalf("expected 1 event, got %d", len(events))
+ }
+ if events[0].GenAI != nil && events[0].GenAI.Usage != nil {
+ t.Fatalf("usage = %#v, want none for a non-Gemini harness", events[0].GenAI.Usage)
+ }
+}
+
+type geminiTokenPoint struct {
+ session, model, tokenType string
+ value int64
+}
+
+// newGeminiTokenUsageMetric builds gemini_cli.token.usage the way Gemini CLI's
+// recordCustomTokenUsageMetrics records it: one monotonic cumulative counter whose series are
+// split by the common attributes (session.id, installation.id, interactive, auth_type) plus model
+// and a type of input, output, thought, cache or tool. Every series of one collection carries the
+// collection timestamp.
+func newGeminiTokenUsageMetric(ts time.Time, points []geminiTokenPoint) pmetric.Metrics {
+ metrics := pmetric.NewMetrics()
+ rm := metrics.ResourceMetrics().AppendEmpty()
+ rm.Resource().Attributes().PutStr("service.name", "gemini-cli")
+ rm.Resource().Attributes().PutStr("service.version", "0.9.0")
+ metric := rm.ScopeMetrics().AppendEmpty().Metrics().AppendEmpty()
+ metric.SetName("gemini_cli.token.usage")
+ metric.SetDescription("Counts the total number of tokens used.")
+ sum := metric.SetEmptySum()
+ sum.SetAggregationTemporality(pmetric.AggregationTemporalityCumulative)
+ sum.SetIsMonotonic(true)
+ for _, p := range points {
+ dp := sum.DataPoints().AppendEmpty()
+ dp.SetStartTimestamp(pcommon.NewTimestampFromTime(ts.Add(-time.Minute)))
+ dp.SetTimestamp(pcommon.NewTimestampFromTime(ts))
+ dp.SetIntValue(p.value)
+ dp.Attributes().PutStr("session.id", p.session)
+ dp.Attributes().PutStr("installation.id", "6f1e2b4c-0d3a-4e5f-9a8b-7c6d5e4f3a2b")
+ dp.Attributes().PutBool("interactive", true)
+ dp.Attributes().PutStr("auth_type", "oauth-personal")
+ dp.Attributes().PutStr("model", p.model)
+ dp.Attributes().PutStr("type", p.tokenType)
+ }
+ return metrics
+}
+
+type geminiMetricUsage struct {
+ input, output, cacheRead, reasoning int64
+ unmapped []string
+}
+
+func sumGeminiMetricUsage(t *testing.T, events []Event) map[string]*geminiMetricUsage {
+ t.Helper()
+ out := map[string]*geminiMetricUsage{}
+ for _, event := range events {
+ if event.Event.Action != "token.usage" || event.Harness.Name != "gemini_cli" {
+ t.Fatalf("event = %#v harness %q, want gemini_cli token.usage", event.Event, event.Harness.Name)
+ }
+ key := event.Session.ID + "/" + event.Model
+ got := out[key]
+ if got == nil {
+ got = &geminiMetricUsage{}
+ out[key] = got
+ }
+ usage := event.GenAI.Usage
+ mapped := false
+ if usage.InputTokens != nil {
+ got.input += *usage.InputTokens
+ mapped = true
+ }
+ if usage.OutputTokens != nil {
+ got.output += *usage.OutputTokens
+ mapped = true
+ }
+ if usage.CacheRead != nil && usage.CacheRead.InputTokens != nil {
+ got.cacheRead += *usage.CacheRead.InputTokens
+ mapped = true
+ }
+ if usage.Reasoning != nil && usage.Reasoning.OutputTokens != nil {
+ got.reasoning += *usage.Reasoning.OutputTokens
+ mapped = true
+ }
+ if !mapped {
+ got.unmapped = append(got.unmapped, event.GenAI.Token.Type)
+ }
+ }
+ return out
+}
+
+// The metric carries the same five Gemini counts as the api_response log, one per series, so it
+// gets the same reading: the input series loses its cached subset and gains the tool-use prompt,
+// the output series gains thoughts, thought is the reasoning breakdown and cache is cache read.
+// Siblings are matched on the full attribute set, so two models and two sessions in one export
+// never borrow each other's counts.
+func TestEventsFromMetricsMapsGeminiTokenTypes(t *testing.T) {
+ ts := time.Unix(1760000060, 0).UTC()
+ metrics := newGeminiTokenUsageMetric(ts, []geminiTokenPoint{
+ {"gemini-session-1", "gemini-2.5-pro", "input", 17000},
+ {"gemini-session-1", "gemini-2.5-pro", "output", 450},
+ {"gemini-session-1", "gemini-2.5-pro", "thought", 420},
+ {"gemini-session-1", "gemini-2.5-pro", "cache", 8000},
+ {"gemini-session-1", "gemini-2.5-pro", "tool", 600},
+ {"gemini-session-1", "gemini-2.5-flash", "input", 900},
+ {"gemini-session-1", "gemini-2.5-flash", "output", 40},
+ {"gemini-session-1", "gemini-2.5-flash", "thought", 0},
+ {"gemini-session-1", "gemini-2.5-flash", "cache", 0},
+ {"gemini-session-1", "gemini-2.5-flash", "tool", 0},
+ {"gemini-session-2", "gemini-2.5-pro", "input", 3000},
+ {"gemini-session-2", "gemini-2.5-pro", "output", 10},
+ {"gemini-session-2", "gemini-2.5-pro", "thought", 5},
+ {"gemini-session-2", "gemini-2.5-pro", "cache", 2048},
+ {"gemini-session-2", "gemini-2.5-pro", "tool", 0},
+ })
+
+ events := NewConverter(Options{}).EventsFromMetrics(metrics)
+ if len(events) != 15 {
+ t.Fatalf("expected one event per datapoint (15), got %d", len(events))
+ }
+ got := sumGeminiMetricUsage(t, events)
+ want := map[string]geminiMetricUsage{
+ "gemini-session-1/gemini-2.5-pro": {input: 17000 - 8000 + 600, output: 450 + 420, cacheRead: 8000, reasoning: 420},
+ "gemini-session-1/gemini-2.5-flash": {input: 900, output: 40},
+ "gemini-session-2/gemini-2.5-pro": {input: 3000 - 2048, output: 10 + 5, cacheRead: 2048, reasoning: 5},
+ }
+ for key, w := range want {
+ g := got[key]
+ if g == nil {
+ t.Fatalf("no events for %s", key)
+ }
+ if g.input != w.input || g.output != w.output || g.cacheRead != w.cacheRead || g.reasoning != w.reasoning {
+ t.Fatalf("%s usage = input %d output %d cache_read %d reasoning %d, want %d/%d/%d/%d",
+ key, g.input, g.output, g.cacheRead, g.reasoning, w.input, w.output, w.cacheRead, w.reasoning)
+ }
+ // tool is folded into input, so its own datapoint must not add to any total.
+ if len(g.unmapped) != 1 || g.unmapped[0] != "tool" {
+ t.Fatalf("%s unmapped token types = %v, want only tool", key, g.unmapped)
+ }
+ }
+ for _, event := range events {
+ if event.Raw["metric_value"] == nil {
+ t.Fatalf("raw metric_value missing: %#v", event.Raw)
+ }
+ }
+}
+
+// Cumulative series reach the exporter as running totals, so the input series' adjusted value
+// must itself be a running total: the cached and tool series of the same collection are running
+// totals too, and differencing two collections of (input - cache + tool) gives exactly the
+// interval's uncached input.
+func TestEventsFromMetricsGeminiCumulativeCollectionsStayConsistent(t *testing.T) {
+ first := newGeminiTokenUsageMetric(time.Unix(1760000060, 0).UTC(), []geminiTokenPoint{
+ {"s", "gemini-2.5-pro", "input", 12000},
+ {"s", "gemini-2.5-pro", "cache", 8000},
+ {"s", "gemini-2.5-pro", "tool", 0},
+ {"s", "gemini-2.5-pro", "output", 350},
+ {"s", "gemini-2.5-pro", "thought", 420},
+ })
+ second := newGeminiTokenUsageMetric(time.Unix(1760000120, 0).UTC(), []geminiTokenPoint{
+ {"s", "gemini-2.5-pro", "input", 17000},
+ {"s", "gemini-2.5-pro", "cache", 8000},
+ {"s", "gemini-2.5-pro", "tool", 600},
+ {"s", "gemini-2.5-pro", "output", 450},
+ {"s", "gemini-2.5-pro", "thought", 420},
+ })
+ converter := NewConverter(Options{})
+ a := sumGeminiMetricUsage(t, converter.EventsFromMetrics(first))["s/gemini-2.5-pro"]
+ b := sumGeminiMetricUsage(t, converter.EventsFromMetrics(second))["s/gemini-2.5-pro"]
+ if a.input != 4000 || b.input != 9600 {
+ t.Fatalf("cumulative uncached input = %d then %d, want 4000 then 9600", a.input, b.input)
+ }
+ if delta := b.input - a.input; delta != 5000-0+600 {
+ t.Fatalf("interval uncached input = %d, want 5600 (5000 new prompt, no new cache, 600 tool)", delta)
+ }
+ if a.output != 770 || b.output != 870 {
+ t.Fatalf("cumulative output = %d then %d, want 770 then 870", a.output, b.output)
+ }
+}
+
+// Other harnesses' token metrics are not touched by the Gemini reading.
+func TestEventsFromMetricsGeminiAdjustmentIsScopedToGeminiMetric(t *testing.T) {
+ metrics := pmetric.NewMetrics()
+ rm := metrics.ResourceMetrics().AppendEmpty()
+ rm.Resource().Attributes().PutStr("service.name", "agent-api")
+ metric := rm.ScopeMetrics().AppendEmpty().Metrics().AppendEmpty()
+ metric.SetName("gen_ai.client.token.usage")
+ sum := metric.SetEmptySum()
+ sum.SetAggregationTemporality(pmetric.AggregationTemporalityDelta)
+ for tokenType, value := range map[string]int64{"input": 100, "output": 20, "cache": 60} {
+ dp := sum.DataPoints().AppendEmpty()
+ dp.SetIntValue(value)
+ dp.Attributes().PutStr("gen_ai.token.type", tokenType)
+ }
+ for _, event := range NewConverter(Options{}).EventsFromMetrics(metrics) {
+ usage := event.GenAI.Usage
+ if usage.InputTokens != nil && *usage.InputTokens != 100 {
+ t.Fatalf("input_tokens = %d, want 100 as reported", *usage.InputTokens)
+ }
+ if usage.OutputTokens != nil && *usage.OutputTokens != 20 {
+ t.Fatalf("output_tokens = %d, want 20 as reported", *usage.OutputTokens)
+ }
+ }
+}
diff --git a/docs/cli/token-usage.mdx b/docs/cli/token-usage.mdx
index bf2e42b2..5d64b515 100644
--- a/docs/cli/token-usage.mdx
+++ b/docs/cli/token-usage.mdx
@@ -51,17 +51,19 @@ from. A turn with no token attribution is a turn whose runtime never reported an
| fx (Vercel Labs) | input, output, cache read, cache creation | Reported (`cost_usd`) | Yes | Yes |
| GitHub Copilot CLI | input, output, cache read, cache creation, reasoning | Not reported | Yes | Yes |
| OpenClaw Gateway | input, output, cache read, cache creation | Not reported on the hook | Yes, per model response | Yes |
+| Gemini CLI | input, output, cache read, reasoning | Not emitted by Gemini CLI | Yes, per model response | When local user context is present |
OpenClaw reports usage on its `llm_output` hook, which is a *conversation* hook -- OpenClaw withholds those from every non-bundled plugin until `plugins.entries.beacon-endpoint.hooks.allowConversationAccess` is set in its config. An OpenClaw endpoint collecting prompts, tools, commands and files while reporting no tokens at all is almost always that key, and `beacon endpoint hooks status --harness openclaw` says so. OpenClaw does compute a per-turn price, from an operator-configured cost table rather than from a provider report, so Beacon does not record it as a reported cost. See [OpenClaw Gateway](/runtimes/openclaw-gateway).
+Gemini CLI reports each model response on its `gemini_cli.api_response` log record and again on the `gemini_cli.token.usage` counter, under Gemini's own counts rather than the semconv names. Those counts are not disjoint: Gemini's input (`promptTokenCount`) already includes the cached content, its output (`candidatesTokenCount`) leaves out thinking tokens, and its tool-use prompt tokens are input that the prompt count does not hold. Beacon therefore records input as prompt minus cached plus tool-use prompt, cache read as the cached count, and output as candidates plus thoughts with the thoughts as its reasoning breakdown, so a response's Beacon total equals Gemini's own `total_token_count`. Gemini also restates input and output on a `gen_ai.client.inference.operation.details` record; Beacon reads usage only from `api_response`, so a response is counted once, and the counter is de-duplicated against the log because both carry Gemini's `session.id`. These shapes are pinned from Gemini CLI's telemetry source rather than from a recorded session.
+
Cline reports usage once per task rather than per model call, because Beacon's rollups sum `gen_ai.usage` across events and reporting at both granularities would count every token twice. fx reports cumulative totals, which Beacon differences into per-turn deltas for the same reason. GitHub Copilot CLI reports assistant message output tokens and cumulative shutdown model totals; Beacon records the message output directly, then differences shutdown totals for input, cache, reasoning, and any output not already counted.
**Collected through the generic OpenTelemetry path, not yet verified against captured payloads:**
| Runtime | Status |
|---------|--------|
-| Gemini CLI | Usage is captured when the runtime emits the OTel GenAI semconv names (`gen_ai.usage.*` attributes, or a `gen_ai.client.token.usage` metric split by `token_type`). The generic path is tested; these runtimes' own payloads have not been captured and pinned. |
-| VS Code Copilot | As above |
+| VS Code Copilot | Usage is captured when the runtime emits the OTel GenAI semconv names (`gen_ai.usage.*` attributes, or a `gen_ai.client.token.usage` metric split by `token_type`). The generic path is tested; these runtimes' own payloads have not been captured and pinned. |
| Factory Droid | As above |
| Grok Bot | Reaches Beacon only through Cursor's server-side OpenTelemetry export, so usage arrives only if that export carries the semconv names |
| goose | goose's `chat` spans carry the full `gen_ai.usage.*` set, cache reads and writes included, under the exact semconv names -- that much is read out of the runtime rather than hoped for. What is conditional is whether it arrives: usage reaches Beacon only over manually configured OTLP, so a hooks-only goose setup is correctly silent rather than faulty. goose reports no cost. See [goose](/runtimes/goose) |
diff --git a/docs/runtimes/gemini-cli.mdx b/docs/runtimes/gemini-cli.mdx
index 3acba442..c10f49c2 100644
--- a/docs/runtimes/gemini-cli.mdx
+++ b/docs/runtimes/gemini-cli.mdx
@@ -39,6 +39,7 @@ Gemini CLI is not currently configured through Beacon's hook adapter.
|------|---------|
| Prompt telemetry | Supported when emitted through Gemini OTLP |
| Command, tool, and file telemetry | Supported for prompts, tool calls, MCP activity, file operations, and approval-related events emitted through OTLP |
+| Token usage | Supported from the `gemini_cli.api_response` log and `gemini_cli.token.usage` counter: input, output, cache read, and thinking tokens as reasoning, per session. Gemini CLI reports no cost. See [Token usage](/cli/token-usage) for how Gemini's overlapping counts are made disjoint |
| Local JSONL and dashboard | Supported |
| MDM deployment | Supported through the system-mode package or MDM-managed config when `gemini` is included in the harness list |