Skip to content

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

serialize traces

Justin D'Souza4482a816824b
diff --git a/cli/beacon-hooks/internal/logging/endpoint_event_test.go b/cli/beacon-hooks/internal/logging/endpoint_event_test.go
index 6e7faa12..0474b497 100644
--- a/cli/beacon-hooks/internal/logging/endpoint_event_test.go
+++ b/cli/beacon-hooks/internal/logging/endpoint_event_test.go
@@ -532,6 +532,49 @@ func TestEndpointEventDoesNotOverwriteAReportedProvider(t *testing.T) {
}
}
+func TestEndpointEventDerivesTraceFromSessionAndToolCall(t *testing.T) {
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ logger := NewLoggerForPlatform("post-tool", "claude")
+ if err := logger.EndpointEvent("command.executed", "command", "info", "done", map[string]interface{}{
+ "session": map[string]interface{}{"id": "s1"},
+ "gen_ai": map[string]interface{}{
+ "tool": map[string]interface{}{"call": map[string]interface{}{"id": "toolu_1"}},
+ },
+ }); err != nil {
+ t.Fatalf("EndpointEvent returned error: %v", err)
+ }
+
+ event := decodeSingleEndpointEvent(t, logPath)
+ trace, _ := event["trace"].(map[string]interface{})
+ if trace["id"] != "session:claude_code:s1" || trace["span_id"] != "toolu_1" {
+ t.Fatalf("trace = %#v, want session trace id and tool span id", trace)
+ }
+}
+
+func TestEndpointEventKeepsReportedTrace(t *testing.T) {
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ logger := NewLoggerForPlatform("post-tool", "claude")
+ if err := logger.EndpointEvent("command.executed", "command", "info", "done", map[string]interface{}{
+ "session": map[string]interface{}{"id": "s1"},
+ "trace": map[string]interface{}{"id": "trace-1", "span_id": "span-1"},
+ "gen_ai": map[string]interface{}{
+ "tool": map[string]interface{}{"call": map[string]interface{}{"id": "toolu_1"}},
+ },
+ }); err != nil {
+ t.Fatalf("EndpointEvent returned error: %v", err)
+ }
+
+ event := decodeSingleEndpointEvent(t, logPath)
+ trace, _ := event["trace"].(map[string]interface{})
+ if trace["id"] != "trace-1" || trace["span_id"] != "span-1" {
+ t.Fatalf("trace = %#v, want reported trace preserved", trace)
+ }
+}
+
// An event with no model must not gain an empty one, and must not gain a gen_ai block it had no
// reason to have.
func TestEndpointEventWithoutAModelIsUntouched(t *testing.T) {
diff --git a/cli/beacon-hooks/internal/logging/logging.go b/cli/beacon-hooks/internal/logging/logging.go
index 18a19a12..28714b37 100644
--- a/cli/beacon-hooks/internal/logging/logging.go
+++ b/cli/beacon-hooks/internal/logging/logging.go
@@ -128,6 +128,7 @@ func (l *Logger) EndpointEventWithFidelity(action, category, severity, message,
event[key] = value
}
normalizeEventModel(event)
+ attachDerivedTrace(event)
if err := writeEndpointJSON(path, event); err != nil {
fmt.Fprintf(os.Stderr, "logging: failed to write endpoint event to %s: %v\n", path, err)
return err
@@ -248,6 +249,44 @@ func (l *Logger) baseEndpointEvent(action, category, severity, message, fidelity
return event
}
+func attachDerivedTrace(event map[string]interface{}) {
+ if event == nil {
+ return
+ }
+ session, _ := event["session"].(map[string]interface{})
+ sessionID, _ := session["id"].(string)
+ if strings.TrimSpace(sessionID) == "" {
+ return
+ }
+ trace, _ := event["trace"].(map[string]interface{})
+ if trace == nil {
+ trace = map[string]interface{}{}
+ }
+ if id, _ := trace["id"].(string); strings.TrimSpace(id) == "" {
+ harness, _ := event["harness"].(map[string]interface{})
+ harnessName, _ := harness["name"].(string)
+ if traceID := asymptoteobserve.DerivedTraceIDForSession(harnessName, sessionID); traceID != "" {
+ trace["id"] = traceID
+ }
+ }
+ if spanID, _ := trace["span_id"].(string); strings.TrimSpace(spanID) == "" {
+ if callID := endpointToolCallID(event); callID != "" {
+ trace["span_id"] = callID
+ }
+ }
+ if len(trace) > 0 {
+ event["trace"] = trace
+ }
+}
+
+func endpointToolCallID(event map[string]interface{}) string {
+ genAI, _ := event["gen_ai"].(map[string]interface{})
+ tool, _ := genAI["tool"].(map[string]interface{})
+ call, _ := tool["call"].(map[string]interface{})
+ id, _ := call["id"].(string)
+ return strings.TrimSpace(id)
+}
+
func cloudRunFields() map[string]interface{} {
run := map[string]interface{}{}
if provider := firstEnv("BEACON_RUN_PROVIDER"); provider != "" {
diff --git a/cli/beacon/internal/endpoint/dashboard/traces.go b/cli/beacon/internal/endpoint/dashboard/traces.go
index 8639b24a..d5ada57b 100644
--- a/cli/beacon/internal/endpoint/dashboard/traces.go
+++ b/cli/beacon/internal/endpoint/dashboard/traces.go
@@ -490,7 +490,11 @@ func traceEventFromRecord(record EventRecord, number int) TraceEventV1 {
func traceProjectionID(event schema.Event) string {
if event.Trace != nil && strings.TrimSpace(event.Trace.ID) != "" {
- return "trace:" + strings.TrimSpace(event.Trace.ID)
+ id := strings.TrimSpace(event.Trace.ID)
+ if strings.HasPrefix(id, "session:") || strings.HasPrefix(id, "trace:") || strings.HasPrefix(id, "event:") {
+ return id
+ }
+ return "trace:" + id
}
if event.Session != nil && strings.TrimSpace(event.Session.ID) != "" {
harness := asymptoteobserve.NormalizeHarnessName(event.Harness.Name)
diff --git a/cli/beacon/internal/endpoint/writer/writer.go b/cli/beacon/internal/endpoint/writer/writer.go
index 1d6fd85a..5b8f6cf8 100644
--- a/cli/beacon/internal/endpoint/writer/writer.go
+++ b/cli/beacon/internal/endpoint/writer/writer.go
@@ -62,6 +62,7 @@ func AppendEvent(event schema.Event, opts Options) (string, error) {
if opts.RotateArchives < 1 {
opts.RotateArchives = DefaultRotateArchives
}
+ asymptoteobserve.AttachDerivedTrace(&event)
event = SanitizeEvent(event, opts.MaxBytes)
if err := event.Validate(); err != nil {
return "", err
diff --git a/cli/beacon/internal/endpoint/writer/writer_test.go b/cli/beacon/internal/endpoint/writer/writer_test.go
index 81e7d990..fda0c4fe 100644
--- a/cli/beacon/internal/endpoint/writer/writer_test.go
+++ b/cli/beacon/internal/endpoint/writer/writer_test.go
@@ -339,6 +339,35 @@ func TestAppendEventStampsAStableEventID(t *testing.T) {
}
}
+func TestAppendEventDerivesTraceFromSessionAndToolCall(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ event := schema.NewEvent(schema.NewEventOptions{
+ Action: "command.executed",
+ Harness: schema.HarnessInfo{Name: "claude_code"},
+ Message: "Shell command executed",
+ })
+ event.Timestamp = "2026-08-21T18:00:01Z"
+ event.Session = &schema.SessionInfo{ID: "s1"}
+ event.Command = &schema.CommandInfo{Command: "echo hi"}
+ event.GenAI = &schema.GenAIInfo{Tool: &schema.GenAIToolInfo{Call: &schema.GenAIToolCallInfo{ID: "toolu_1"}}}
+
+ if _, err := AppendEvent(event, Options{Path: path}); err != nil {
+ t.Fatalf("AppendEvent returned error: %v", err)
+ }
+
+ line, err := LastLine(path)
+ if err != nil {
+ t.Fatalf("read last line: %v", err)
+ }
+ var written schema.Event
+ if err := json.Unmarshal([]byte(line), &written); err != nil {
+ t.Fatalf("decode written event: %v", err)
+ }
+ if written.Trace == nil || written.Trace.ID != "session:claude_code:s1" || written.Trace.SpanID != "toolu_1" {
+ t.Fatalf("trace = %#v, want derived session trace and tool span", written.Trace)
+ }
+}
+
// The regression the call ID exists to fix: after harness normalization both
// capture paths report claude_code, and the collector's batch lands seconds
// after the hook's write. Nothing but a shared call ID can collapse that pair.
diff --git a/pkg/asymptoteobserve/identity.go b/pkg/asymptoteobserve/identity.go
index 7732845c..670c81b7 100644
--- a/pkg/asymptoteobserve/identity.go
+++ b/pkg/asymptoteobserve/identity.go
@@ -124,6 +124,62 @@ func eventUUID(kind, name string) string {
return fmt.Sprintf("%s-%s-%s-%s-%s", out[0:8], out[8:12], out[12:16], out[16:20], out[20:32])
}
+// DerivedTraceIDForSession is the trace identity used by non-OTLP collection paths.
+//
+// OTLP spans already arrive with a provider trace id. Hook, plugin and poll paths usually do not,
+// but they do carry the runtime session id that the dashboard already uses as the trace grouping
+// key. Writing that grouping key into event.trace makes the event self-describing for consumers
+// that do not know Beacon's dashboard fallback rules.
+func DerivedTraceIDForSession(harnessName, sessionID string) string {
+ sessionID = strings.TrimSpace(sessionID)
+ if sessionID == "" {
+ return ""
+ }
+ harness := NormalizeHarnessName(harnessName)
+ if harness == "" {
+ harness = strings.TrimSpace(harnessName)
+ }
+ if harness == "" {
+ return "session:" + sessionID
+ }
+ return "session:" + harness + ":" + sessionID
+}
+
+// AttachDerivedTrace fills event.trace from the stable identities Beacon already promotes.
+// Existing trace fields, such as OTLP trace/span ids, always win.
+func AttachDerivedTrace(event *Event) {
+ if event == nil || event.Session == nil {
+ return
+ }
+ traceID := ""
+ if event.Trace != nil {
+ traceID = strings.TrimSpace(event.Trace.ID)
+ }
+ if traceID == "" {
+ traceID = DerivedTraceIDForSession(event.Harness.Name, event.Session.ID)
+ }
+ if traceID == "" {
+ return
+ }
+ if event.Trace == nil {
+ event.Trace = &TraceInfo{}
+ }
+ if strings.TrimSpace(event.Trace.ID) == "" {
+ event.Trace.ID = traceID
+ }
+ if strings.TrimSpace(event.Trace.SpanID) == "" {
+ event.Trace.SpanID = ToolCallID(event)
+ }
+}
+
+// ToolCallID returns the promoted runtime identifier for one tool invocation.
+func ToolCallID(event *Event) string {
+ if event == nil || event.GenAI == nil || event.GenAI.Tool == nil || event.GenAI.Tool.Call == nil {
+ return ""
+ }
+ return strings.TrimSpace(event.GenAI.Tool.Call.ID)
+}
+
// ContextUsedKeys and ContextLimitKeys are the names a runtime uses for how full the model's
// context was on a call, and for the window it was measured against.
//
diff --git a/pkg/asymptoteobserve/pipeline.go b/pkg/asymptoteobserve/pipeline.go
index 6346633a..44d19974 100644
--- a/pkg/asymptoteobserve/pipeline.go
+++ b/pkg/asymptoteobserve/pipeline.go
@@ -142,6 +142,7 @@ func copyEvent(event Event) Event {
out := event
out.Run = cloneRun(event.Run)
out.Session = cloneSession(event.Session)
+ out.Trace = cloneTrace(event.Trace)
if event.Tool != nil {
tool := *event.Tool
out.Tool = &tool
@@ -191,6 +192,14 @@ func copyEvent(event Event) Event {
return out
}
+func cloneTrace(trace *TraceInfo) *TraceInfo {
+ if trace == nil {
+ return nil
+ }
+ out := *trace
+ return &out
+}
+
func cloneTyped[T any](input *T) *T {
if input == nil {
return nil