Skip to content

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

Add trace identity, usage cost, and int64 token counts to event schema

Claudeb3937ca5792d
diff --git a/CLAUDE.md b/CLAUDE.md
index 59f6247f..f742f7d9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -261,7 +261,8 @@ Use these npm trusted publisher values:
- Avoid tests that require root, real `launchctl` service changes, Wazuh, a live collector, or external network access.
- For macOS-only behavior, gate tests with `runtime.GOOS == "darwin"` or assert the non-Darwin contract explicitly.
- Keep endpoint event schema fields stable: `vendor`, `product`, `schema_version`, required event fields, and Wazuh-compatible JSONL output are release contracts.
-- Preserve optional event fields for agent-native metadata (`session`, `tool`, `file`, `command`, `mcp`, `approval`, `content`, `model`, `repository`, and `branch`) without changing existing required field semantics.
+- Preserve optional event fields for agent-native metadata (`session`, `trace`, `tool`, `file`, `command`, `mcp`, `approval`, `content`, `model`, `repository`, and `branch`) without changing existing required field semantics.
+- Keep `gen_ai.usage` as the single canonical token-usage representation: normalize all runtime token telemetry (span attributes, metric datapoints, legacy `llm.usage.*` aliases) into it, mirror OTel GenAI semconv JSON names exactly, and never add parallel or per-harness token fields. `gen_ai.usage.cost_usd` carries runtime-reported cost only; do not derive cost from local pricing tables.
- When adding a new signal, include stable identifiers/counts/hashes alongside any retained raw content, and route raw fields through redaction, sanitization, truncation, and event-size controls.
- Keep the dashboard read-only. It should inspect local status and JSONL events but must not mutate endpoint configuration or telemetry.
- Keep the release readiness guidance in `README.md` up to date when install, packaging, collector, or dashboard behavior changes.
diff --git a/cli/beacon/internal/endpoint/schema/event.go b/cli/beacon/internal/endpoint/schema/event.go
index 24888380..0f4c6218 100644
--- a/cli/beacon/internal/endpoint/schema/event.go
+++ b/cli/beacon/internal/endpoint/schema/event.go
@@ -48,6 +48,7 @@ type EndpointInfo = asymptoteobserve.EndpointInfo
type UserInfo = asymptoteobserve.UserInfo
type HarnessInfo = asymptoteobserve.HarnessInfo
type SessionInfo = asymptoteobserve.SessionInfo
+type TraceInfo = asymptoteobserve.TraceInfo
type RunInfo = asymptoteobserve.RunInfo
type ToolInfo = asymptoteobserve.ToolInfo
type FileInfo = asymptoteobserve.FileInfo
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
index 6dd2558e..2b44deb6 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
@@ -623,19 +623,19 @@ func GenAIToolFromAttrs(attrs map[string]interface{}) *GenAIToolInfo {
func GenAIUsageFromAttrs(attrs map[string]interface{}) *GenAIUsageInfo {
usage := &GenAIUsageInfo{}
- if value, ok := IntAttr(attrs, "gen_ai.usage.cache_creation.input_tokens"); ok {
+ if value, ok := Int64Attr(attrs, "gen_ai.usage.cache_creation.input_tokens"); ok {
usage.CacheCreation = &GenAIUsageCacheCreationInfo{InputTokens: &value}
}
- if value, ok := IntAttr(attrs, "gen_ai.usage.cache_read.input_tokens"); ok {
+ if value, ok := Int64Attr(attrs, "gen_ai.usage.cache_read.input_tokens"); ok {
usage.CacheRead = &GenAIUsageCacheReadInfo{InputTokens: &value}
}
- if value, ok := IntAttr(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"); ok {
usage.InputTokens = &value
}
- if value, ok := IntAttr(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"); ok {
usage.OutputTokens = &value
}
- if value, ok := IntAttr(attrs, "gen_ai.usage.reasoning.output_tokens"); ok {
+ if value, ok := Int64Attr(attrs, "gen_ai.usage.reasoning.output_tokens"); ok {
usage.Reasoning = &GenAIUsageReasoningInfo{OutputTokens: &value}
}
if IsZeroJSON(usage) {
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
index 9dfe697d..917ffdfa 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
@@ -1,6 +1,8 @@
package beaconevent
import (
+ "encoding/json"
+ "strings"
"testing"
"time"
@@ -8,6 +10,31 @@ import (
"go.opentelemetry.io/collector/pdata/ptrace"
)
+// Guards against the exporter Event mirror struct drifting from the shared
+// asymptoteobserve schema: new optional fields must survive JSON marshaling.
+func TestEventMirrorSerializesTraceAndUsageCost(t *testing.T) {
+ event := NewEvent("token.usage", "metric", "info", "claude_code", time.Unix(1700000000, 0).UTC())
+ event.Trace = &TraceInfo{ID: "0123456789abcdef0123456789abcdef", SpanID: "0123456789abcdef", ParentSpanID: "fedcba9876543210"}
+ cost := 0.0123
+ input := int64(120)
+ event.GenAI = &GenAIInfo{Usage: &GenAIUsageInfo{InputTokens: &input, CostUSD: &cost}}
+
+ data, err := json.Marshal(event)
+ if err != nil {
+ t.Fatalf("marshal event: %v", err)
+ }
+ text := string(data)
+ for _, want := range []string{
+ `"trace":{"id":"0123456789abcdef0123456789abcdef","span_id":"0123456789abcdef","parent_span_id":"fedcba9876543210"}`,
+ `"cost_usd":0.0123`,
+ `"input_tokens":120`,
+ } {
+ if !strings.Contains(text, want) {
+ t.Fatalf("JSON missing %s: %s", want, text)
+ }
+ }
+}
+
func TestEventsFromTracesNormalizesObserveSDKSpan(t *testing.T) {
span, traces := newObserveSDKTraceSpan("agent.plan")
attrs := span.Attributes()
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go
index d78f32ce..e10dbb2c 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go
@@ -17,6 +17,7 @@ type EndpointInfo = asymptoteobserve.EndpointInfo
type UserInfo = asymptoteobserve.UserInfo
type HarnessInfo = asymptoteobserve.HarnessInfo
type SessionInfo = asymptoteobserve.SessionInfo
+type TraceInfo = asymptoteobserve.TraceInfo
type RunInfo = asymptoteobserve.RunInfo
type ToolInfo = asymptoteobserve.ToolInfo
type FileInfo = asymptoteobserve.FileInfo
@@ -68,6 +69,7 @@ type Event struct {
Origin asymptoteobserve.Origin `json:"origin,omitempty"`
Run *RunInfo `json:"run,omitempty"`
Session *SessionInfo `json:"session,omitempty"`
+ Trace *TraceInfo `json:"trace,omitempty"`
Tool *ToolInfo `json:"tool,omitempty"`
File *FileInfo `json:"file,omitempty"`
Command *CommandInfo `json:"command,omitempty"`
diff --git a/pkg/asymptoteobserve/event.go b/pkg/asymptoteobserve/event.go
index e4c8366a..ec4fec65 100644
--- a/pkg/asymptoteobserve/event.go
+++ b/pkg/asymptoteobserve/event.go
@@ -77,6 +77,12 @@ type SessionInfo struct {
WorkingDirectory string `json:"working_directory,omitempty"`
}
+type TraceInfo struct {
+ ID string `json:"id,omitempty"`
+ SpanID string `json:"span_id,omitempty"`
+ ParentSpanID string `json:"parent_span_id,omitempty"`
+}
+
type RunInfo struct {
Provider string `json:"provider,omitempty"`
RunID string `json:"run_id,omitempty"`
@@ -269,22 +275,27 @@ type GenAIToolInfo struct {
}
type GenAIUsageCacheCreationInfo struct {
- InputTokens *int `json:"input_tokens,omitempty"`
+ InputTokens *int64 `json:"input_tokens,omitempty"`
}
type GenAIUsageCacheReadInfo struct {
- InputTokens *int `json:"input_tokens,omitempty"`
+ InputTokens *int64 `json:"input_tokens,omitempty"`
}
type GenAIUsageReasoningInfo struct {
- OutputTokens *int `json:"output_tokens,omitempty"`
+ OutputTokens *int64 `json:"output_tokens,omitempty"`
}
+// GenAIUsageInfo mirrors the OpenTelemetry GenAI semconv usage attribute
+// names. Token counts are int64 to match OTLP integer values. CostUSD has no
+// semconv equivalent; it carries runtime-reported USD cost only (for example
+// Claude Code's cost metric) and is never derived from local pricing tables.
type GenAIUsageInfo struct {
CacheCreation *GenAIUsageCacheCreationInfo `json:"cache_creation,omitempty"`
CacheRead *GenAIUsageCacheReadInfo `json:"cache_read,omitempty"`
- InputTokens *int `json:"input_tokens,omitempty"`
- OutputTokens *int `json:"output_tokens,omitempty"`
+ CostUSD *float64 `json:"cost_usd,omitempty"`
+ InputTokens *int64 `json:"input_tokens,omitempty"`
+ OutputTokens *int64 `json:"output_tokens,omitempty"`
Reasoning *GenAIUsageReasoningInfo `json:"reasoning,omitempty"`
}
@@ -338,6 +349,7 @@ type Event struct {
Origin Origin `json:"origin,omitempty"`
Run *RunInfo `json:"run,omitempty"`
Session *SessionInfo `json:"session,omitempty"`
+ Trace *TraceInfo `json:"trace,omitempty"`
Tool *ToolInfo `json:"tool,omitempty"`
File *FileInfo `json:"file,omitempty"`
Command *CommandInfo `json:"command,omitempty"`
diff --git a/pkg/asymptoteobserve/event_test.go b/pkg/asymptoteobserve/event_test.go
index d0ebf877..8babf8da 100644
--- a/pkg/asymptoteobserve/event_test.go
+++ b/pkg/asymptoteobserve/event_test.go
@@ -43,7 +43,7 @@ func TestNewEventSetsRequiredInvariants(t *testing.T) {
event.GenAI = &GenAIInfo{
Provider: &GenAIProviderInfo{Name: "openai"},
Request: &GenAIRequestInfo{Model: "gpt-4o"},
- Usage: &GenAIUsageInfo{InputTokens: intPtr(10), OutputTokens: intPtr(20)},
+ Usage: &GenAIUsageInfo{InputTokens: int64Ptr(10), OutputTokens: int64Ptr(20)},
}
if err := event.Validate(); err != nil {
t.Fatalf("Validate rejected optional telemetry fields: %v", err)
@@ -97,10 +97,65 @@ func TestValidateOriginValues(t *testing.T) {
}
}
-func intPtr(value int) *int {
+func int64Ptr(value int64) *int64 {
return &value
}
+func float64Ptr(value float64) *float64 {
+ return &value
+}
+
+func TestTraceAndUsageCostSerializeWithSemconvNames(t *testing.T) {
+ event := NewEvent(NewEventOptions{Action: "token.usage", Harness: HarnessInfo{Name: "claude_code"}})
+ event.Trace = &TraceInfo{ID: "0123456789abcdef0123456789abcdef", SpanID: "0123456789abcdef", ParentSpanID: "fedcba9876543210"}
+ event.GenAI = &GenAIInfo{
+ Usage: &GenAIUsageInfo{
+ InputTokens: int64Ptr(120),
+ OutputTokens: int64Ptr(45),
+ CacheCreation: &GenAIUsageCacheCreationInfo{InputTokens: int64Ptr(30)},
+ CacheRead: &GenAIUsageCacheReadInfo{InputTokens: int64Ptr(90)},
+ Reasoning: &GenAIUsageReasoningInfo{OutputTokens: int64Ptr(15)},
+ CostUSD: float64Ptr(0.0123),
+ },
+ }
+ if err := event.Validate(); err != nil {
+ t.Fatalf("Validate rejected trace and usage fields: %v", err)
+ }
+ data, err := json.Marshal(event)
+ if err != nil {
+ t.Fatalf("marshal event: %v", err)
+ }
+ text := string(data)
+ for _, want := range []string{
+ `"trace":{"id":"0123456789abcdef0123456789abcdef","span_id":"0123456789abcdef","parent_span_id":"fedcba9876543210"}`,
+ `"input_tokens":120`,
+ `"output_tokens":45`,
+ `"cache_creation":{"input_tokens":30}`,
+ `"cache_read":{"input_tokens":90}`,
+ `"reasoning":{"output_tokens":15}`,
+ `"cost_usd":0.0123`,
+ } {
+ if !strings.Contains(text, want) {
+ t.Fatalf("JSON missing %s: %s", want, text)
+ }
+ }
+}
+
+func TestTraceAndUsageCostOmittedWhenUnset(t *testing.T) {
+ event := NewEvent(NewEventOptions{Action: "tool.invoked", Harness: HarnessInfo{Name: "cursor"}})
+ event.GenAI = &GenAIInfo{Usage: &GenAIUsageInfo{InputTokens: int64Ptr(1)}}
+ data, err := json.Marshal(event)
+ if err != nil {
+ t.Fatalf("marshal event: %v", err)
+ }
+ text := string(data)
+ for _, field := range []string{`"trace"`, `"cost_usd"`} {
+ if strings.Contains(text, field) {
+ t.Fatalf("unset additive field %s leaked into JSON: %s", field, text)
+ }
+ }
+}
+
func TestRunAndOriginAreOmittedWhenUnset(t *testing.T) {
event := NewEvent(NewEventOptions{Action: "tool.invoked", Harness: HarnessInfo{Name: "cursor"}})
data, err := json.Marshal(event)