The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
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.goindex 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.goindex 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.goindex 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.mdindex 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 dedupediff --git a/collector-builder/exporter/beaconjsonexporter/gemini_usage_e2e_test.go b/collector-builder/exporter/beaconjsonexporter/gemini_usage_e2e_test.gonew file mode 100644index 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.goindex 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.gonew file mode 100644index 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.gonew file mode 100644index 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.mdxindex 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.mdxindex 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 |