Skip to content

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

Fix token usage normalization for Claude Code telemetry

Claudeb764214bf9d7
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
index 35373047..afb7a8f2 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
@@ -492,6 +492,13 @@ func (c Converter) usageEventFromDataPoint(resourceAttrs map[string]interface{},
event := NewEvent(action, "metric", "info", HarnessName(attrs, metric.Name()), Timestamp(ts.AsTime()))
event.Message = metric.Name()
c.PopulateCommon(&event, attrs)
+ // The datapoint value is the authoritative usage for this event. Drop any
+ // gen_ai.usage.* that PopulateCommon read from merged attributes so a stray
+ // usage attribute on the resource or datapoint cannot ride along on every
+ // expanded datapoint event and inflate aggregated totals.
+ if event.GenAI != nil {
+ event.GenAI.Usage = nil
+ }
if action == "cost.usage" {
cost := value
if event.GenAI == nil {
@@ -779,18 +786,23 @@ func GenAIToolFromAttrs(attrs map[string]interface{}) *GenAIToolInfo {
return tool
}
+// GenAIUsageFromAttrs normalizes runtime token usage into the canonical
+// gen_ai.usage struct. Alongside the OTel GenAI and legacy llm.usage.* semconv
+// names it accepts Claude Code's bare claude_code.llm_request span attribute
+// names (input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens)
+// so span-level usage and the per-step session drilldown carry real counts.
func GenAIUsageFromAttrs(attrs map[string]interface{}) *GenAIUsageInfo {
usage := &GenAIUsageInfo{}
- if value, ok := Int64Attr(attrs, "gen_ai.usage.cache_creation.input_tokens", "gen_ai.usage.cache_creation_input_tokens"); ok {
+ if value, ok := Int64Attr(attrs, "gen_ai.usage.cache_creation.input_tokens", "gen_ai.usage.cache_creation_input_tokens", "cache_creation_tokens"); ok {
usage.CacheCreation = &GenAIUsageCacheCreationInfo{InputTokens: &value}
}
- if value, ok := Int64Attr(attrs, "gen_ai.usage.cache_read.input_tokens", "gen_ai.usage.cache_read_input_tokens"); ok {
+ if value, ok := Int64Attr(attrs, "gen_ai.usage.cache_read.input_tokens", "gen_ai.usage.cache_read_input_tokens", "cache_read_tokens"); ok {
usage.CacheRead = &GenAIUsageCacheReadInfo{InputTokens: &value}
}
- if value, ok := Int64Attr(attrs, "gen_ai.usage.input_tokens", "llm.usage.prompt_tokens", "gen_ai.usage.prompt_tokens"); ok {
+ if value, ok := Int64Attr(attrs, "gen_ai.usage.input_tokens", "llm.usage.prompt_tokens", "gen_ai.usage.prompt_tokens", "input_tokens"); ok {
usage.InputTokens = &value
}
- if value, ok := Int64Attr(attrs, "gen_ai.usage.output_tokens", "llm.usage.completion_tokens", "gen_ai.usage.completion_tokens"); ok {
+ if value, ok := Int64Attr(attrs, "gen_ai.usage.output_tokens", "llm.usage.completion_tokens", "gen_ai.usage.completion_tokens", "output_tokens"); ok {
usage.OutputTokens = &value
}
if value, ok := Int64Attr(attrs, "gen_ai.usage.reasoning.output_tokens"); ok {
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
index 8cdea40b..305ac7cd 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
@@ -144,6 +144,46 @@ func TestEventsFromTracesNormalizesClaudeAgentSDKSpan(t *testing.T) {
}
}
+func TestEventFromSpanNormalizesClaudeCodeLLMRequestUsage(t *testing.T) {
+ // Claude Code's claude_code.llm_request span records token usage under bare
+ // attribute names (input_tokens, output_tokens, cache_read_tokens,
+ // cache_creation_tokens), not the gen_ai.usage.* semconv names. These must
+ // normalize into the canonical gen_ai.usage so the per-step session
+ // drilldown and span-level attribution carry real usage.
+ traces := ptrace.NewTraces()
+ rs := traces.ResourceSpans().AppendEmpty()
+ rs.Resource().Attributes().PutStr("service.name", "claude-code")
+ span := rs.ScopeSpans().AppendEmpty().Spans().AppendEmpty()
+ span.SetName("claude_code.llm_request")
+ span.Attributes().PutStr("session.id", "session-span")
+ span.Attributes().PutStr("model", "claude-sonnet-4-5")
+ span.Attributes().PutInt("input_tokens", 1200)
+ span.Attributes().PutInt("output_tokens", 340)
+ span.Attributes().PutInt("cache_read_tokens", 8000)
+ span.Attributes().PutInt("cache_creation_tokens", 256)
+
+ events := NewConverter(Options{}).EventsFromTraces(traces)
+ if len(events) != 1 {
+ t.Fatalf("expected 1 event, got %d", len(events))
+ }
+ usage := events[0].GenAI.Usage
+ if usage == nil {
+ t.Fatalf("usage missing on span event: %#v", events[0].GenAI)
+ }
+ if usage.InputTokens == nil || *usage.InputTokens != 1200 {
+ t.Fatalf("input_tokens = %v, want 1200", usage.InputTokens)
+ }
+ if usage.OutputTokens == nil || *usage.OutputTokens != 340 {
+ t.Fatalf("output_tokens = %v, want 340", usage.OutputTokens)
+ }
+ if usage.CacheRead == nil || usage.CacheRead.InputTokens == nil || *usage.CacheRead.InputTokens != 8000 {
+ t.Fatalf("cache_read = %#v, want 8000", usage.CacheRead)
+ }
+ if usage.CacheCreation == nil || usage.CacheCreation.InputTokens == nil || *usage.CacheCreation.InputTokens != 256 {
+ t.Fatalf("cache_creation = %#v, want 256", usage.CacheCreation)
+ }
+}
+
func TestEventFromSpanCapturesTraceIdentity(t *testing.T) {
span, traces := newObserveSDKTraceSpan("agent.step")
span.SetTraceID(pcommon.TraceID([16]byte{0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef}))
@@ -279,6 +319,52 @@ func TestEventsFromMetricsExpandsClaudeCodeTokenUsageDataPoints(t *testing.T) {
}
}
+func TestEventsFromMetricsTokenUsageIgnoresStrayUsageAttributes(t *testing.T) {
+ // A token.usage datapoint event must carry only the value from its own
+ // datapoint, not gen_ai.usage.* attributes that happen to ride along on the
+ // resource or datapoint. Otherwise the stray field is attached to every
+ // expanded datapoint event and double-counted by tokens.Aggregate.
+ metrics := pmetric.NewMetrics()
+ resourceMetrics := metrics.ResourceMetrics().AppendEmpty()
+ resourceMetrics.Resource().Attributes().PutStr("service.name", "claude-code")
+ // Stray usage attribute that overlaps the per-datapoint token type.
+ resourceMetrics.Resource().Attributes().PutInt("gen_ai.usage.input_tokens", 999)
+ metric := resourceMetrics.ScopeMetrics().AppendEmpty().Metrics().AppendEmpty()
+ metric.SetName("claude_code.token.usage")
+ metric.SetUnit("tokens")
+ sum := metric.SetEmptySum()
+ sum.SetAggregationTemporality(pmetric.AggregationTemporalityDelta)
+ sum.SetIsMonotonic(true)
+ ts := pcommon.NewTimestampFromTime(time.Unix(1700000200, 0).UTC())
+ for _, tokenType := range []string{"input", "output"} {
+ dp := sum.DataPoints().AppendEmpty()
+ dp.SetTimestamp(ts)
+ dp.SetIntValue(10)
+ dp.Attributes().PutStr("type", tokenType)
+ }
+
+ events := NewConverter(Options{}).EventsFromMetrics(metrics)
+ if len(events) != 2 {
+ t.Fatalf("expected 2 events, got %d", len(events))
+ }
+ for _, event := range events {
+ usage := event.GenAI.Usage
+ if usage == nil {
+ t.Fatalf("usage missing on event: %#v", event.GenAI)
+ }
+ if usage.OutputTokens != nil {
+ // The output datapoint event must not also carry the stray input.
+ if usage.InputTokens != nil {
+ t.Fatalf("output datapoint leaked input_tokens=%d from stray attribute", *usage.InputTokens)
+ }
+ continue
+ }
+ if usage.InputTokens == nil || *usage.InputTokens != 10 {
+ t.Fatalf("input datapoint = %#v, want input_tokens=10 from datapoint value", usage)
+ }
+ }
+}
+
func TestEventsFromMetricsCapturesCostUsage(t *testing.T) {
metrics := pmetric.NewMetrics()
resourceMetrics := metrics.ResourceMetrics().AppendEmpty()