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
Add trace identity, usage cost, and int64 token counts to event schema
Claudeb3937ca5792d
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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.goindex 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.EndpointInfotype UserInfo = asymptoteobserve.UserInfotype HarnessInfo = asymptoteobserve.HarnessInfotype SessionInfo = asymptoteobserve.SessionInfo+type TraceInfo = asymptoteobserve.TraceInfotype RunInfo = asymptoteobserve.RunInfotype ToolInfo = asymptoteobserve.ToolInfotype FileInfo = asymptoteobserve.FileInfodiff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.goindex 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.goindex 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 beaconeventimport (+ "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.goindex 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.EndpointInfotype UserInfo = asymptoteobserve.UserInfotype HarnessInfo = asymptoteobserve.HarnessInfotype SessionInfo = asymptoteobserve.SessionInfo+type TraceInfo = asymptoteobserve.TraceInfotype RunInfo = asymptoteobserve.RunInfotype ToolInfo = asymptoteobserve.ToolInfotype 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.goindex 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.goindex 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)