Skip to content

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

Make the trace store answer the same question as the JSONL scan

Claude1a5d461ba200
diff --git a/cli/beacon/internal/endpoint/dashboard/trace_store.go b/cli/beacon/internal/endpoint/dashboard/trace_store.go
index 6f2d8c85..bc92957f 100644
--- a/cli/beacon/internal/endpoint/dashboard/trace_store.go
+++ b/cli/beacon/internal/endpoint/dashboard/trace_store.go
@@ -6,7 +6,6 @@ import (
"fmt"
"os"
"path/filepath"
- "regexp"
"sort"
"strings"
"time"
@@ -16,9 +15,18 @@ import (
const traceStoreFile = "traces.db"
+// traceStoreSchemaVersion is written to the database's user_version. The store
+// is a rebuildable index over the runtime log, never a source of truth, so a
+// version bump drops the tables and reindexes rather than migrating them.
+const traceStoreSchemaVersion = 2
+
type traceStore struct {
- dbPath string
- logPath string
+ dbPath string
+ // logPath is the log to read; sourceKey is the same path normalized, and is
+ // what every row is scoped by. Sibling logs in one directory share one
+ // traces.db, so two sources can hold the same trace or event id.
+ logPath string
+ sourceKey string
}
type traceStoreStatus struct {
@@ -29,15 +37,6 @@ type traceStoreStatus struct {
IndexedAt string `json:"indexed_at,omitempty"`
}
-type traceSearchOptions struct {
- Literal bool
- CaseSensitive bool
- Sources []string
- Tool string
- ScanTraces int
- ScanEventsPerTrace int
-}
-
func TraceStorePath(logPath string) string {
return defaultTraceStorePath(logPath)
}
@@ -62,7 +61,21 @@ func defaultTraceStorePath(logPath string) string {
}
func openTraceStore(logPath string) *traceStore {
- return &traceStore{dbPath: defaultTraceStorePath(logPath), logPath: logPath}
+ return &traceStore{
+ dbPath: defaultTraceStorePath(logPath),
+ logPath: logPath,
+ sourceKey: traceSourceKey(logPath),
+ }
+}
+
+// traceSourceKey normalizes a log path so the same log reached by a relative
+// and an absolute path indexes once rather than twice.
+func traceSourceKey(logPath string) string {
+ abs, err := filepath.Abs(logPath)
+ if err != nil {
+ return logPath
+ }
+ return filepath.Clean(abs)
}
func (s *traceStore) db() (*sql.DB, error) {
@@ -93,32 +106,57 @@ func sqliteURI(path string) string {
}
func ensureTraceStoreSchema(db *sql.DB) error {
+ var version int
+ if err := db.QueryRow(`PRAGMA user_version`).Scan(&version); err != nil {
+ return err
+ }
+ // Any version but the current one is dropped, 0 included: a database this
+ // build has never stamped either is empty, where the drops are no-ops, or
+ // predates the stamp and holds tables CREATE TABLE IF NOT EXISTS would
+ // leave in their old shape.
+ if version != traceStoreSchemaVersion {
+ for _, table := range []string{"trace_search", "trace_events", "traces", "trace_index_state"} {
+ if _, err := db.Exec(`DROP TABLE IF EXISTS ` + table); err != nil {
+ return err
+ }
+ }
+ }
stmts := []string{
`CREATE TABLE IF NOT EXISTS trace_index_state (
source_key TEXT PRIMARY KEY,
fingerprint TEXT NOT NULL,
indexed_at TEXT NOT NULL
)`,
+ // Trace ids are unique within one source, not across a directory of
+ // them, so the key carries the source.
`CREATE TABLE IF NOT EXISTS traces (
- id TEXT PRIMARY KEY,
source_key TEXT NOT NULL,
+ id TEXT NOT NULL,
summary_json TEXT NOT NULL,
updated_at TEXT,
- created_at TEXT NOT NULL
+ created_at TEXT NOT NULL,
+ PRIMARY KEY (source_key, id)
)`,
`CREATE INDEX IF NOT EXISTS traces_by_source_updated ON traces (source_key, updated_at DESC)`,
+ // event_number is the event's ordinal within its trace, which is what
+ // makes a row unique. event_id is the runtime's own name for the call
+ // and is deliberately not part of the key: two events can share one --
+ // a repeated log line, or a hook and an OTLP capture of the same call,
+ // whose ids are derived to match -- and the JSONL path keeps both.
`CREATE TABLE IF NOT EXISTS trace_events (
+ source_key TEXT NOT NULL,
trace_id TEXT NOT NULL,
- event_id TEXT NOT NULL,
event_number INTEGER NOT NULL,
+ event_id TEXT NOT NULL,
event_type TEXT,
tool_name TEXT,
event_json TEXT NOT NULL,
created_at TEXT NOT NULL,
- PRIMARY KEY (trace_id, event_id)
+ PRIMARY KEY (source_key, trace_id, event_number)
)`,
- `CREATE INDEX IF NOT EXISTS trace_events_by_trace_number ON trace_events (trace_id, event_number)`,
+ `CREATE INDEX IF NOT EXISTS trace_events_by_event_id ON trace_events (source_key, trace_id, event_id)`,
`CREATE TABLE IF NOT EXISTS trace_search (
+ source_key TEXT NOT NULL,
trace_id TEXT NOT NULL,
event_id TEXT,
source TEXT NOT NULL,
@@ -127,14 +165,18 @@ func ensureTraceStoreSchema(db *sql.DB) error {
event_number INTEGER,
body TEXT NOT NULL
)`,
- `CREATE INDEX IF NOT EXISTS trace_search_by_trace_source ON trace_search (trace_id, source)`,
- `CREATE INDEX IF NOT EXISTS trace_search_by_event_type ON trace_search (event_type)`,
+ `CREATE INDEX IF NOT EXISTS trace_search_by_source_trace ON trace_search (source_key, source, trace_id)`,
}
for _, stmt := range stmts {
if _, err := db.Exec(stmt); err != nil {
return err
}
}
+ if version != traceStoreSchemaVersion {
+ if _, err := db.Exec(fmt.Sprintf(`PRAGMA user_version = %d`, traceStoreSchemaVersion)); err != nil {
+ return err
+ }
+ }
return nil
}
@@ -146,7 +188,7 @@ func (s *traceStore) ensureCurrent() error {
defer db.Close()
fingerprint := traceLogFingerprint(s.logPath)
var current string
- err = db.QueryRow(`SELECT fingerprint FROM trace_index_state WHERE source_key = ?`, s.logPath).Scan(&current)
+ err = db.QueryRow(`SELECT fingerprint FROM trace_index_state WHERE source_key = ?`, s.sourceKey).Scan(&current)
if err == nil && current == fingerprint {
return nil
}
@@ -176,23 +218,23 @@ func (s *traceStore) reindexDB(db *sql.DB, fingerprint string) error {
}
defer tx.Rollback()
for _, stmt := range []string{
- `DELETE FROM trace_search WHERE trace_id IN (SELECT id FROM traces WHERE source_key = ?)`,
- `DELETE FROM trace_events WHERE trace_id IN (SELECT id FROM traces WHERE source_key = ?)`,
+ `DELETE FROM trace_search WHERE source_key = ?`,
+ `DELETE FROM trace_events WHERE source_key = ?`,
`DELETE FROM traces WHERE source_key = ?`,
} {
- if _, err := tx.Exec(stmt, s.logPath); err != nil {
+ if _, err := tx.Exec(stmt, s.sourceKey); err != nil {
return err
}
}
now := time.Now().UTC().Format(time.RFC3339Nano)
for _, agg := range traces {
- if err := insertTraceAggregate(tx, s.logPath, agg, now); err != nil {
+ if err := insertTraceAggregate(tx, s.sourceKey, agg, now); err != nil {
return err
}
}
if _, err := tx.Exec(`INSERT INTO trace_index_state (source_key, fingerprint, indexed_at) VALUES (?, ?, ?)
ON CONFLICT(source_key) DO UPDATE SET fingerprint = excluded.fingerprint, indexed_at = excluded.indexed_at`,
- s.logPath, fingerprint, now); err != nil {
+ s.sourceKey, fingerprint, now); err != nil {
return err
}
return tx.Commit()
@@ -203,12 +245,12 @@ func insertTraceAggregate(tx *sql.Tx, sourceKey string, agg *traceAggregate, now
if err != nil {
return err
}
- if _, err := tx.Exec(`INSERT INTO traces (id, source_key, summary_json, updated_at, created_at) VALUES (?, ?, ?, ?, ?)`,
- agg.summary.ID, sourceKey, string(summaryJSON), agg.summary.UpdatedAt, now); err != nil {
+ if _, err := tx.Exec(`INSERT INTO traces (source_key, id, summary_json, updated_at, created_at) VALUES (?, ?, ?, ?, ?)`,
+ sourceKey, agg.summary.ID, string(summaryJSON), agg.summary.UpdatedAt, now); err != nil {
return err
}
- if _, err := tx.Exec(`INSERT INTO trace_search (trace_id, source, body) VALUES (?, 'trace', ?)`,
- agg.summary.ID, traceSummarySearchBody(agg.summary)); err != nil {
+ if _, err := tx.Exec(`INSERT INTO trace_search (source_key, trace_id, source, body) VALUES (?, ?, 'trace', ?)`,
+ sourceKey, agg.summary.ID, traceSummaryHaystack(agg.summary)); err != nil {
return err
}
for _, event := range agg.events {
@@ -223,14 +265,14 @@ func insertTraceAggregate(tx *sql.Tx, sourceKey string, agg *traceAggregate, now
if event.Command != nil && toolName == "" {
toolName = "command"
}
- if _, err := tx.Exec(`INSERT INTO trace_events (trace_id, event_id, event_number, event_type, tool_name, event_json, created_at)
- VALUES (?, ?, ?, ?, ?, ?, ?)`,
- agg.summary.ID, event.ID, event.Number, event.Type, toolName, string(eventJSON), now); err != nil {
+ if _, err := tx.Exec(`INSERT INTO trace_events (source_key, trace_id, event_number, event_id, event_type, tool_name, event_json, created_at)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+ sourceKey, agg.summary.ID, event.Number, event.ID, event.Type, toolName, string(eventJSON), now); err != nil {
return err
}
- if _, err := tx.Exec(`INSERT INTO trace_search (trace_id, event_id, source, event_type, tool_name, event_number, body)
- VALUES (?, ?, 'event', ?, ?, ?, ?)`,
- agg.summary.ID, event.ID, event.Type, toolName, event.Number, traceEventSearchBody(event)); err != nil {
+ if _, err := tx.Exec(`INSERT INTO trace_search (source_key, trace_id, event_id, source, event_type, tool_name, event_number, body)
+ VALUES (?, ?, ?, 'event', ?, ?, ?, ?)`,
+ sourceKey, agg.summary.ID, event.ID, event.Type, toolName, event.Number, traceEventHaystack(event)); err != nil {
return err
}
}
@@ -247,10 +289,10 @@ func (s *traceStore) Status() (traceStoreStatus, error) {
}
defer db.Close()
status := traceStoreStatus{Path: s.dbPath}
- _ = db.QueryRow(`SELECT COUNT(*) FROM traces WHERE source_key = ?`, s.logPath).Scan(&status.Traces)
- _ = db.QueryRow(`SELECT COUNT(*) FROM trace_events WHERE trace_id IN (SELECT id FROM traces WHERE source_key = ?)`, s.logPath).Scan(&status.Events)
- _ = db.QueryRow(`SELECT COUNT(*) FROM trace_search WHERE trace_id IN (SELECT id FROM traces WHERE source_key = ?)`, s.logPath).Scan(&status.IndexRows)
- _ = db.QueryRow(`SELECT indexed_at FROM trace_index_state WHERE source_key = ?`, s.logPath).Scan(&status.IndexedAt)
+ _ = db.QueryRow(`SELECT COUNT(*) FROM traces WHERE source_key = ?`, s.sourceKey).Scan(&status.Traces)
+ _ = db.QueryRow(`SELECT COUNT(*) FROM trace_events WHERE source_key = ?`, s.sourceKey).Scan(&status.Events)
+ _ = db.QueryRow(`SELECT COUNT(*) FROM trace_search WHERE source_key = ?`, s.sourceKey).Scan(&status.IndexRows)
+ _ = db.QueryRow(`SELECT indexed_at FROM trace_index_state WHERE source_key = ?`, s.sourceKey).Scan(&status.IndexedAt)
return status, nil
}
@@ -266,7 +308,9 @@ func (s *traceStore) List(query TraceQuery) (TraceListResultV1, error) {
return TraceListResultV1{}, err
}
filtered := make([]TraceSummaryV1, 0, len(summaries))
- matchingIDs, err := s.matchingTraceIDs(query, traceSearchOptions{})
+ // traceAggregateMatches keeps a trace whose summary or any of its events
+ // match, so the store searches both kinds of row.
+ matchingIDs, err := s.matchingTraceIDs(query.Q, "trace", "event")
if err != nil {
return TraceListResultV1{}, err
}
@@ -307,7 +351,7 @@ func (s *traceStore) List(query TraceQuery) (TraceListResultV1, error) {
}, nil
}
-func (s *traceStore) Search(query TraceQuery, opts traceSearchOptions) (TraceSearchResultV1, error) {
+func (s *traceStore) Search(query TraceQuery) (TraceSearchResultV1, error) {
if !traceStoreSupportsQuery(query) {
return TraceSearchResultV1{}, errTraceStoreUnsupported
}
@@ -321,7 +365,7 @@ func (s *traceStore) Search(query TraceQuery, opts traceSearchOptions) (TraceSea
resp := TraceSearchResultV1{ResultLevel: query.ResultLevel, Limit: limit, Filters: activeTraceFilters(query)}
switch query.ResultLevel {
case "event":
- events, err := s.searchEvents(query, opts, limit)
+ events, err := s.searchEvents(query, limit)
if err != nil {
return TraceSearchResultV1{}, err
}
@@ -334,7 +378,9 @@ func (s *traceStore) Search(query TraceQuery, opts traceSearchOptions) (TraceSea
if err != nil {
return TraceSearchResultV1{}, err
}
- matching, err := s.matchingTraceIDs(query, opts)
+ // Unlike List, trace-level search matches the summary alone -- the
+ // JSONL path uses traceSummaryMatches here, not traceAggregateMatches.
+ matching, err := s.matchingTraceIDs(query.Q, "trace")
if err != nil {
return TraceSearchResultV1{}, err
}
@@ -373,7 +419,7 @@ func (s *traceStore) Show(id string, query TraceQuery) (TraceShowResultV1, bool,
}
defer db.Close()
var summaryJSON string
- err = db.QueryRow(`SELECT summary_json FROM traces WHERE source_key = ? AND id = ?`, s.logPath, id).Scan(&summaryJSON)
+ err = db.QueryRow(`SELECT summary_json FROM traces WHERE source_key = ? AND id = ?`, s.sourceKey, id).Scan(&summaryJSON)
if err == sql.ErrNoRows {
return TraceShowResultV1{}, false, nil
}
@@ -442,7 +488,7 @@ func (s *traceStore) loadSummaries() ([]TraceSummaryV1, error) {
return nil, err
}
defer db.Close()
- rows, err := db.Query(`SELECT summary_json FROM traces WHERE source_key = ?`, s.logPath)
+ rows, err := db.Query(`SELECT summary_json FROM traces WHERE source_key = ?`, s.sourceKey)
if err != nil {
return nil, err
}
@@ -462,10 +508,13 @@ func (s *traceStore) loadSummaries() ([]TraceSummaryV1, error) {
return summaries, rows.Err()
}
-func (s *traceStore) matchingTraceIDs(query TraceQuery, opts traceSearchOptions) (map[string]bool, error) {
+// matchingTraceIDs returns the traces whose indexed text matches the free-text
+// query, looking only at the named row kinds ("trace" for summaries, "event"
+// for events).
+func (s *traceStore) matchingTraceIDs(q string, kinds ...string) (map[string]bool, error) {
out := map[string]bool{}
- needle := strings.TrimSpace(query.Q)
- if needle == "" {
+ needle := strings.TrimSpace(q)
+ if needle == "" || len(kinds) == 0 {
return out, nil
}
db, err := s.db()
@@ -473,7 +522,11 @@ func (s *traceStore) matchingTraceIDs(query TraceQuery, opts traceSearchOptions)
return nil, err
}
defer db.Close()
- rows, err := db.Query(`SELECT trace_id, body FROM trace_search WHERE trace_id IN (SELECT id FROM traces WHERE source_key = ?) AND source IN (`+sourcePlaceholders(opts.Sources)+`)`, append([]interface{}{s.logPath}, sourcesOrDefault(opts.Sources)...)...)
+ args := []any{s.sourceKey}
+ for _, kind := range kinds {
+ args = append(args, kind)
+ }
+ rows, err := db.Query(`SELECT trace_id, body FROM trace_search WHERE source_key = ? AND source IN (`+placeholders(len(kinds))+`)`, args...)
if err != nil {
return nil, err
}
@@ -483,7 +536,7 @@ func (s *traceStore) matchingTraceIDs(query TraceQuery, opts traceSearchOptions)
if err := rows.Scan(&id, &body); err != nil {
return nil, err
}
- if textMatches(body, needle, opts.Literal, opts.CaseSensitive) {
+ if matchesAllTerms(body, needle) {
out[id] = true
}
}
@@ -495,7 +548,7 @@ type traceEventSearchRows struct {
total int
}
-func (s *traceStore) searchEvents(query TraceQuery, opts traceSearchOptions, limit int) (traceEventSearchRows, error) {
+func (s *traceStore) searchEvents(query TraceQuery, limit int) (traceEventSearchRows, error) {
db, err := s.db()
if err != nil {
return traceEventSearchRows{}, err
@@ -508,6 +561,7 @@ func (s *traceStore) searchEvents(query TraceQuery, opts traceSearchOptions, lim
sortTraceSummaries(summaries)
result := traceEventSearchRows{}
allowedTypes := traceEventTypeSet(query.EventTypes)
+ needle := strings.TrimSpace(query.Q)
for _, summary := range summaries {
if query.State != "" && !strings.EqualFold(summary.Sharing.State, query.State) {
continue
@@ -520,13 +574,10 @@ func (s *traceStore) searchEvents(query TraceQuery, opts traceSearchOptions, lim
return traceEventSearchRows{}, err
}
for _, event := range events {
- if query.Q != "" && !textMatches(traceEventSearchBody(event), query.Q, opts.Literal, opts.CaseSensitive) {
- continue
- }
if len(allowedTypes) > 0 && !allowedTypes[traceEventTypeAlias(event.Type)] && !allowedTypes[strings.ToLower(event.Type)] {
continue
}
- if opts.Tool != "" && (event.Tool == nil || !strings.EqualFold(event.Tool.Name, opts.Tool)) {
+ if needle != "" && !traceEventMatches(event, needle) {
continue
}
result.total++
@@ -534,7 +585,7 @@ func (s *traceStore) searchEvents(query TraceQuery, opts traceSearchOptions, lim
result.returned = append(result.returned, TraceEventMatchV1{
Trace: summary,
Event: event,
- Snippet: traceSnippet(event, query.Q),
+ Snippet: traceSnippet(event, needle),
Score: 1,
})
}
@@ -544,7 +595,7 @@ func (s *traceStore) searchEvents(query TraceQuery, opts traceSearchOptions, lim
}
func (s *traceStore) loadTraceEvents(db *sql.DB, traceID string, eventTypes []string) ([]TraceEventV1, error) {
- rows, err := db.Query(`SELECT event_json FROM trace_events WHERE trace_id = ? ORDER BY event_number`, traceID)
+ rows, err := db.Query(`SELECT event_json FROM trace_events WHERE source_key = ? AND trace_id = ? ORDER BY event_number`, s.sourceKey, traceID)
if err != nil {
return nil, err
}
@@ -567,22 +618,6 @@ func (s *traceStore) loadTraceEvents(db *sql.DB, traceID string, eventTypes []st
return events, rows.Err()
}
-func (s *traceStore) loadOneEvent(db *sql.DB, traceID, eventID string) (TraceEventV1, bool, error) {
- var raw string
- err := db.QueryRow(`SELECT event_json FROM trace_events WHERE trace_id = ? AND event_id = ?`, traceID, eventID).Scan(&raw)
- if err == sql.ErrNoRows {
- return TraceEventV1{}, false, nil
- }
- if err != nil {
- return TraceEventV1{}, false, err
- }
- var event TraceEventV1
- if err := json.Unmarshal([]byte(raw), &event); err != nil {
- return TraceEventV1{}, false, err
- }
- return event, true, nil
-}
-
func spansFromEvents(events []TraceEventV1) []TraceSpanV1 {
spans := map[string]*TraceSpanV1{}
for _, event := range events {
@@ -615,111 +650,12 @@ func traceLogFingerprint(logPath string) string {
return strings.Join(parts, "|")
}
-func traceSummarySearchBody(summary TraceSummaryV1) string {
- fields := []string{
- summary.ID,
- summary.Title,
- summary.Preview,
- summary.Harness.Name,
- summary.Harness.Version,
- summary.Sharing.State,
- summary.Sharing.Visibility,
- summary.Sharing.URL,
+// placeholders builds an n-wide SQL "?,?,..." list.
+func placeholders(n int) string {
+ if n <= 0 {
+ return ""
}
- if summary.Session != nil {
- fields = append(fields, summary.Session.ID, summary.Session.WorkingDirectory)
- }
- if summary.Repository != nil {
- fields = append(fields, summary.Repository.RemoteURL, summary.Repository.Branch, summary.Repository.Ref, summary.Repository.Path)
- }
- if summary.Namespace != nil {
- fields = append(fields, summary.Namespace.ID, summary.Namespace.Slug, summary.Namespace.Name)
- }
- if summary.Trace != nil {
- fields = append(fields, summary.Trace.ID, summary.Trace.RootSpanID)
- }
- return strings.Join(fields, " ")
-}
-
-func traceEventSearchBody(event TraceEventV1) string {
- fields := []string{event.ID, event.Type, event.Action, event.Category, event.Actor, event.Title, event.Summary, event.Model}
- if event.Content != nil {
- fields = append(fields, event.Content.Text, event.Content.Hash)
- }
- if event.Tool != nil {
- fields = append(fields, event.Tool.Name, event.Tool.Command, event.Tool.Path, fmt.Sprint(event.Tool.Arguments), fmt.Sprint(event.Tool.Result))
- }
- if event.Command != nil {
- fields = append(fields, event.Command.Command)
- if event.Command.Output != nil {
- fields = append(fields, event.Command.Output.Text)
- }
- }
- if event.File != nil {
- fields = append(fields, event.File.Path, event.File.Operation, event.File.Language, event.File.DiffHash)
- if event.File.Diff != nil {
- fields = append(fields, event.File.Diff.Text)
- }
- }
- if event.MCP != nil {
- fields = append(fields, event.MCP.Server, event.MCP.Tool, event.MCP.Method, event.MCP.ResourceURI)
- }
- if event.Approval != nil {
- fields = append(fields, event.Approval.Decision, event.Approval.Reason)
- }
- return strings.Join(fields, " ")
-}
-
-func textMatches(body, pattern string, literal, caseSensitive bool) bool {
- body = strings.TrimSpace(body)
- pattern = strings.TrimSpace(pattern)
- if pattern == "" {
- return true
- }
- if literal {
- if caseSensitive {
- return strings.Contains(body, pattern)
- }
- return strings.Contains(strings.ToLower(body), strings.ToLower(pattern))
- }
- expr := pattern
- if !caseSensitive {
- expr = "(?i)" + expr
- }
- re, err := regexp.Compile(expr)
- if err != nil {
- if caseSensitive {
- return strings.Contains(body, pattern)
- }
- return strings.Contains(strings.ToLower(body), strings.ToLower(pattern))
- }
- return re.MatchString(body)
-}
-
-func sourcePlaceholders(sources []string) string {
- values := sourcesOrDefault(sources)
- out := make([]string, len(values))
- for i := range out {
- out[i] = "?"
- }
- return strings.Join(out, ",")
-}
-
-func sourcesOrDefault(sources []string) []interface{} {
- if len(sources) == 0 {
- return []interface{}{"trace", "event"}
- }
- out := make([]interface{}, 0, len(sources))
- for _, source := range sources {
- source = strings.ToLower(strings.TrimSpace(source))
- if source == "trace" || source == "event" {
- out = append(out, source)
- }
- }
- if len(out) == 0 {
- return []interface{}{"trace", "event"}
- }
- return out
+ return strings.TrimSuffix(strings.Repeat("?,", n), ",")
}
func traceEventTypeSet(values []string) map[string]bool {
diff --git a/cli/beacon/internal/endpoint/dashboard/traces.go b/cli/beacon/internal/endpoint/dashboard/traces.go
index 5946d343..e59b4bfa 100644
--- a/cli/beacon/internal/endpoint/dashboard/traces.go
+++ b/cli/beacon/internal/endpoint/dashboard/traces.go
@@ -66,6 +66,12 @@ type traceAggregate struct {
titlePriority int
}
+// The local store is an index over the runtime log, never a second source of
+// truth: it answers the same question the JSONL scan below answers, and any
+// error -- a query it does not support, an unreadable database, a stale index
+// it could not rebuild -- falls back to that scan rather than failing the read.
+// The two paths share one free-text matcher (matchesAllTerms) and one pair of
+// haystacks precisely so the fallback cannot change the answer.
func ReadTraceList(path string, query TraceQuery) (TraceListResultV1, error) {
if result, err := openTraceStore(path).List(query); err == nil {
return result, nil
@@ -109,8 +115,10 @@ func ReadTraceList(path string, query TraceQuery) (TraceListResultV1, error) {
}, nil
}
+// SearchTraces prefers the local store and falls back to scanning JSONL; see
+// ReadTraceList on why a store error is not an error here.
func SearchTraces(path string, query TraceQuery) (TraceSearchResultV1, error) {
- if result, err := openTraceStore(path).Search(query, traceSearchOptions{}); err == nil {
+ if result, err := openTraceStore(path).Search(query); err == nil {
return result, nil
}
if query.ResultLevel == "" {
@@ -169,6 +177,8 @@ func SearchTraces(path string, query TraceQuery) (TraceSearchResultV1, error) {
return resp, nil
}
+// ShowTrace prefers the local store and falls back to scanning JSONL; see
+// ReadTraceList on why a store error is not an error here.
func ShowTrace(path, id string, query TraceQuery) (TraceShowResultV1, bool, error) {
if result, ok, err := openTraceStore(path).Show(id, query); err == nil {
return result, ok, nil
@@ -847,8 +857,15 @@ func traceSpanList(spans map[string]*TraceSpanV1) []TraceSpanV1 {
return out
}
-func traceSummaryMatches(summary TraceSummaryV1, query string) bool {
- haystack := strings.ToLower(strings.Join([]string{
+// traceSummaryHaystack is the text a free-text query is matched against for one
+// trace. The local store indexes this exact string, so the store and the JSONL
+// fallback select the same traces from the same query.
+//
+// Fields are joined with a newline rather than concatenated: strings.Fields
+// splits the query on whitespace, so no term can contain one, and no term can
+// straddle two fields.
+func traceSummaryHaystack(summary TraceSummaryV1) string {
+ return strings.Join([]string{
summary.ID,
summary.Title,
summary.Preview,
@@ -860,17 +877,17 @@ func traceSummaryMatches(summary TraceSummaryV1, query string) bool {
summary.Sharing.State,
summary.Sharing.Visibility,
summary.Sharing.URL,
- }, "\x00"))
- for _, term := range strings.Fields(strings.ToLower(query)) {
- if !strings.Contains(haystack, term) {
- return false
- }
- }
- return true
+ }, "\n")
}
-func traceEventMatches(event TraceEventV1, query string) bool {
- haystack := strings.ToLower(strings.Join([]string{
+func traceSummaryMatches(summary TraceSummaryV1, query string) bool {
+ return matchesAllTerms(traceSummaryHaystack(summary), query)
+}
+
+// traceEventHaystack is the per-event counterpart to traceSummaryHaystack, and
+// is indexed by the local store for the same reason.
+func traceEventHaystack(event TraceEventV1) string {
+ return strings.Join([]string{
event.ID,
event.Type,
event.Action,
@@ -891,7 +908,20 @@ func traceEventMatches(event TraceEventV1, query string) bool {
}),
valueOrEmpty(event.MCP, func(m *TraceMCPV1) string { return m.Server + " " + m.Tool + " " + m.Method + " " + m.ResourceURI }),
valueOrEmpty(event.Approval, func(a *TraceApprovalV1) string { return a.Decision + " " + a.Reason }),
- }, "\x00"))
+ }, "\n")
+}
+
+func traceEventMatches(event TraceEventV1, query string) bool {
+ return matchesAllTerms(traceEventHaystack(event), query)
+}
+
+// matchesAllTerms reports whether every whitespace-separated term in query is a
+// case-insensitive substring of haystack. This is the one free-text matcher
+// Beacon's trace queries use; the store must not reinterpret a query as
+// anything else, or the same search would return different hits depending on
+// whether the index happened to be readable.
+func matchesAllTerms(haystack, query string) bool {
+ haystack = strings.ToLower(haystack)
for _, term := range strings.Fields(strings.ToLower(query)) {
if !strings.Contains(haystack, term) {
return false
diff --git a/cli/beacon/internal/endpoint/dashboard/traces_test.go b/cli/beacon/internal/endpoint/dashboard/traces_test.go
index 77e704c5..5dad11a2 100644
--- a/cli/beacon/internal/endpoint/dashboard/traces_test.go
+++ b/cli/beacon/internal/endpoint/dashboard/traces_test.go
@@ -426,4 +426,197 @@ func TestTraceStoreIndexesAndRefreshesRuntimeLog(t *testing.T) {
}
}
+// traceStoreBlockedLog copies the given log lines into a directory where the
+// trace store cannot be opened (a directory sits where traces.db would go), so
+// a query against the returned path exercises the JSONL fallback.
+func traceStoreBlockedLog(t *testing.T, lines [][]byte) string {
+ t.Helper()
+ path := filepath.Join(t.TempDir(), "logs", "runtime.jsonl")
+ if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {
+ t.Fatalf("mkdir log dir: %v", err)
+ }
+ if err := os.MkdirAll(TraceStorePath(path), 0700); err != nil {
+ t.Fatalf("block trace store path: %v", err)
+ }
+ writeTestLog(t, path, lines...)
+ return path
+}
+
+func traceStoreIndexedLog(t *testing.T, lines [][]byte) string {
+ t.Helper()
+ path := filepath.Join(t.TempDir(), "logs", "runtime.jsonl")
+ if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {
+ t.Fatalf("mkdir log dir: %v", err)
+ }
+ writeTestLog(t, path, lines...)
+ return path
+}
+
+// The store may be faster than scanning JSONL, but it may not answer a
+// different question. A query that reaches the index and the same query that
+// falls back must select the same traces and the same events -- which they do
+// not if the store reinterprets the query as a regular expression, or searches
+// event text where the JSONL path searches only the summary.
+func TestTraceStoreAndJSONLFallbackMatchIdentically(t *testing.T) {
+ prompt := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")
+ prompt.Event.ID = "evt-prompt"
+ prompt.Session = &schema.SessionInfo{ID: "s1", WorkingDirectory: "/repo/a"}
+ prompt.Prompt = &schema.PromptInfo{Text: "Index local traces"}
+ command := testSchemaEvent("2026-06-11T10:01:00Z", "cursor", "command.executed", "command", "repo-a")
+ command.Event.ID = "evt-command"
+ command.Session = prompt.Session
+ command.Command = &schema.CommandInfo{Command: "go test ./internal/endpoint/dashboard"}
+ lines := marshalEvents(t, prompt, command)
+
+ indexed := traceStoreIndexedLog(t, lines)
+ fallback := traceStoreBlockedLog(t, lines)
+
+ queries := []string{
+ "dashboard go", // terms out of order: a substring match, not a regex one
+ "endpoint.dashboard", // "." is a literal here, so this must not match "endpoint/dashboard"
+ "endpoint/dashboard", // ... while the real separator must
+ "go test", // multi-word phrase
+ "(", // not a valid regular expression
+ "index local",
+ "INDEX LOCAL", // matching is case-insensitive
+ "nothing-matches-this",
+ }
+ for _, q := range queries {
+ t.Run(q, func(t *testing.T) {
+ indexedList, err := ReadTraceList(indexed, TraceQuery{EventQuery: EventQuery{Q: q}, Limit: 10})
+ if err != nil {
+ t.Fatalf("indexed list: %v", err)
+ }
+ fallbackList, err := ReadTraceList(fallback, TraceQuery{EventQuery: EventQuery{Q: q}, Limit: 10})
+ if err != nil {
+ t.Fatalf("fallback list: %v", err)
+ }
+ if indexedList.TotalMatched != fallbackList.TotalMatched {
+ t.Errorf("list matched %d traces from the index and %d from JSONL", indexedList.TotalMatched, fallbackList.TotalMatched)
+ }
+
+ for _, level := range []string{"trace", "event"} {
+ indexedSearch, err := SearchTraces(indexed, TraceQuery{EventQuery: EventQuery{Q: q}, ResultLevel: level, Limit: 10})
+ if err != nil {
+ t.Fatalf("indexed %s search: %v", level, err)
+ }
+ fallbackSearch, err := SearchTraces(fallback, TraceQuery{EventQuery: EventQuery{Q: q}, ResultLevel: level, Limit: 10})
+ if err != nil {
+ t.Fatalf("fallback %s search: %v", level, err)
+ }
+ if indexedSearch.TotalMatched != fallbackSearch.TotalMatched {
+ t.Errorf("%s search matched %d from the index and %d from JSONL", level, indexedSearch.TotalMatched, fallbackSearch.TotalMatched)
+ }
+ if len(indexedSearch.Events) != len(fallbackSearch.Events) {
+ t.Fatalf("%s search returned %d events from the index and %d from JSONL", level, len(indexedSearch.Events), len(fallbackSearch.Events))
+ }
+ for i := range indexedSearch.Events {
+ if indexedSearch.Events[i].Event.ID != fallbackSearch.Events[i].Event.ID {
+ t.Errorf("%s search event %d = %q from the index, %q from JSONL", level, i, indexedSearch.Events[i].Event.ID, fallbackSearch.Events[i].Event.ID)
+ }
+ }
+ }
+ })
+ }
+}
+
+// Two events can carry one id -- a repeated log line, or a hook and an OTLP
+// capture of the same call, whose ids are derived to match. The JSONL path
+// keeps both, so the index must too rather than failing the whole reindex.
+func TestTraceStoreKeepsEventsThatShareAnID(t *testing.T) {
+ first := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "command.executed", "command", "repo-a")
+ first.Event.ID = "same-event-id"
+ first.Session = &schema.SessionInfo{ID: "s1"}
+ first.Command = &schema.CommandInfo{Command: "go build ./..."}
+ second := first
+ second.Timestamp = "2026-06-11T10:00:01Z"
+ path := traceStoreIndexedLog(t, marshalEvents(t, first, second))
+
+ status, err := TraceStoreStatus(path)
+ if err != nil {
+ t.Fatalf("TraceStoreStatus returned error: %v", err)
+ }
+ if status.Traces != 1 || status.Events != 2 {
+ t.Fatalf("status = %#v, want 1 trace and 2 events", status)
+ }
+
+ list, err := ReadTraceList(path, TraceQuery{Limit: 10})
+ if err != nil {
+ t.Fatalf("ReadTraceList returned error: %v", err)
+ }
+ if len(list.Traces) != 1 {
+ t.Fatalf("ReadTraceList returned %d traces, want 1", len(list.Traces))
+ }
+
+ show, ok, err := ShowTrace(path, list.Traces[0].ID, TraceQuery{Limit: 10})
+ if err != nil || !ok {
+ t.Fatalf("ShowTrace ok=%v err=%v", ok, err)
+ }
+ if len(show.Events) != 2 {
+ t.Fatalf("ShowTrace returned %d events, want both events that share an id", len(show.Events))
+ }
+}
+
+// Sibling logs in one directory share one traces.db, and two logs can describe
+// the same session. Each must index under its own source rather than colliding.
+func TestTraceStoreScopesTracesBySourceLog(t *testing.T) {
+ dir := filepath.Join(t.TempDir(), "logs")
+ if err := os.MkdirAll(dir, 0700); err != nil {
+ t.Fatalf("mkdir log dir: %v", err)
+ }
+ shared := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")
+ shared.Event.ID = "evt-prompt"
+ shared.Session = &schema.SessionInfo{ID: "shared-session"}
+ shared.Prompt = &schema.PromptInfo{Text: "first log"}
+ other := shared
+ other.Prompt = &schema.PromptInfo{Text: "second log"}
+
+ first := filepath.Join(dir, "runtime.jsonl")
+ second := filepath.Join(dir, "archive.jsonl")
+ writeTestLog(t, first, marshalEvents(t, shared)...)
+ writeTestLog(t, second, marshalEvents(t, other)...)
+ if TraceStorePath(first) != TraceStorePath(second) {
+ t.Fatalf("expected both logs to share one trace store")
+ }
+
+ for _, tc := range []struct{ path, want string }{{first, "first log"}, {second, "second log"}} {
+ status, err := TraceStoreStatus(tc.path)
+ if err != nil {
+ t.Fatalf("TraceStoreStatus(%s) returned error: %v", tc.path, err)
+ }
+ if status.Traces != 1 || status.Events != 1 {
+ t.Fatalf("status for %s = %#v, want 1 trace and 1 event", tc.path, status)
+ }
+ result, err := SearchTraces(tc.path, TraceQuery{EventQuery: EventQuery{Q: tc.want}, ResultLevel: "event", Limit: 10})
+ if err != nil {
+ t.Fatalf("SearchTraces(%s) returned error: %v", tc.path, err)
+ }
+ if result.TotalMatched != 1 {
+ t.Fatalf("searching %s for %q matched %d events, want 1", tc.path, tc.want, result.TotalMatched)
+ }
+ }
+}
+
+// A relative and an absolute path to one log are one source, not two.
+func TestTraceStoreTreatsEquivalentLogPathsAsOneSource(t *testing.T) {
+ path := traceStoreIndexedLog(t, marshalEvents(t, func() schema.Event {
+ event := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")
+ event.Event.ID = "evt-prompt"
+ event.Session = &schema.SessionInfo{ID: "s1"}
+ event.Prompt = &schema.PromptInfo{Text: "one source"}
+ return event
+ }()))
+
+ if _, err := TraceStoreStatus(path); err != nil {
+ t.Fatalf("TraceStoreStatus returned error: %v", err)
+ }
+ status, err := TraceStoreStatus(filepath.Join(filepath.Dir(path), ".", "runtime.jsonl"))
+ if err != nil {
+ t.Fatalf("TraceStoreStatus for the equivalent path returned error: %v", err)
+ }
+ if status.Traces != 1 || status.Events != 1 {
+ t.Fatalf("status = %#v, want the same single indexed trace", status)
+ }
+}
+
func int64Ptr(v int64) *int64 { return &v }