Documentation
¶
Overview ¶
Snapshot persistence helpers: Save/Load write CodeGraphSnapshot records as timestamped JSON files under a directory, and listFiles/readFile provide the file I/O primitives used by SnapshotStore.
Package trace is a git-native session capture and replay CLI for AI coding agents. It records coding sessions as transcripts on orphan git branches, supports a pluggable agent registry (Claude Code, Codex, Copilot, Cursor, Gemini, OpenCode, Pi, and more), and exports spans to OpenTelemetry collectors.
This file (otel_collector.go) implements the OpenTelemetry export path: converting transcript entries into OTel spans, batching them with configurable size and flush intervals, and shipping batches to an OTLP endpoint with exponential-backoff retry.
Index ¶
- Variables
- func BatchSpans(spans []OTelSpan, batchSize int) [][]OTelSpan
- func FormatSnapshot(snapshot CodeGraphSnapshot) string
- type CodeGraph
- func (cg *CodeGraph) AddEdge(edge Edge) error
- func (cg *CodeGraph) AddNode(node Node) error
- func (cg *CodeGraph) GetEdges(nodeID string) []Edge
- func (cg *CodeGraph) GetNode(id string) (Node, bool)
- func (cg *CodeGraph) Persist(path string) error
- func (cg *CodeGraph) QueryNodes(query NodeQuery) []Node
- func (cg *CodeGraph) Snapshot() CodeGraphData
- func (cg *CodeGraph) Stats() Stats
- type CodeGraphData
- type CodeGraphSnapshot
- type ComplexityMetrics
- type Edge
- type EdgeKind
- type GraphDelta
- type GraphStats
- type ModuleInfo
- type Node
- type NodeKind
- type NodeQuery
- type OTelCollector
- type OTelCollectorConfig
- type OTelEvent
- type OTelSpan
- type RetryConfig
- type SnapshotStore
- type SpanBatch
- type Stats
- type SymbolInfo
Constants ¶
This section is empty.
Variables ¶
var ErrNoSnapshots = errors.New("no snapshots found")
ErrNoSnapshots is returned when no snapshots exist in the store.
Functions ¶
func BatchSpans ¶
BatchSpans splits a flat slice of spans into sub-slices of at most batchSize elements each. The final sub-slice may be smaller. A batchSize <= 0 is treated as 1.
func FormatSnapshot ¶
func FormatSnapshot(snapshot CodeGraphSnapshot) string
FormatSnapshot formats a snapshot for display.
Types ¶
type CodeGraph ¶
type CodeGraph struct {
// contains filtered or unexported fields
}
CodeGraph is a directed graph of code symbols and their relationships.
func LoadSnapshot ¶
LoadSnapshot loads a code graph from a JSON file.
func (*CodeGraph) QueryNodes ¶
QueryNodes returns nodes matching the query.
func (*CodeGraph) Snapshot ¶
func (cg *CodeGraph) Snapshot() CodeGraphData
Snapshot creates a serializable export of the graph.
type CodeGraphData ¶
type CodeGraphData struct {
Version string `json:"version"`
SnapshotAt time.Time `json:"snapshot_at"`
Nodes []Node `json:"nodes"`
Edges []Edge `json:"edges"`
}
CodeGraphData represents a serializable export of the code graph.
type CodeGraphSnapshot ¶
type CodeGraphSnapshot struct {
Timestamp time.Time `json:"timestamp"`
SessionID string `json:"session_id"`
ProjectRoot string `json:"project_root"`
GraphStats GraphStats `json:"graph_stats"`
SymbolCount int `json:"symbol_count"`
EdgeCount int `json:"edge_count"`
FileCount int `json:"file_count"`
TopSymbols []SymbolInfo `json:"top_symbols"`
Modules []ModuleInfo `json:"modules"`
Complexity ComplexityMetrics `json:"complexity"`
Delta *GraphDelta `json:"delta,omitempty"` // changes from previous snapshot
}
CodeGraphSnapshot captures the state of the code graph at a point in time. This enables: - Tracking how the codebase evolves across sessions - Comparing graph states to detect structural changes - Building a history of code complexity over time
type ComplexityMetrics ¶
type ComplexityMetrics struct {
AvgCyclomatic float64 `json:"avg_cyclomatic"`
MaxCyclomatic int `json:"max_cyclomatic"`
AvgLOC float64 `json:"avg_loc"`
MaxLOC int `json:"max_loc"`
TotalFunctions int `json:"total_functions"`
}
ComplexityMetrics holds complexity measurements.
type Edge ¶
type Edge struct {
From string `json:"from"`
To string `json:"to"`
Kind EdgeKind `json:"kind"`
Calls int `json:"calls"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
Edge represents a relationship between two nodes.
type GraphDelta ¶
type GraphDelta struct {
FilesAdded int `json:"files_added"`
FilesRemoved int `json:"files_removed"`
FilesModified int `json:"files_modified"`
NodesAdded int `json:"nodes_added"`
NodesRemoved int `json:"nodes_removed"`
EdgesAdded int `json:"edges_added"`
EdgesRemoved int `json:"edges_removed"`
NewSymbols []string `json:"new_symbols"`
RemovedSymbols []string `json:"removed_symbols"`
ComplexityDelta float64 `json:"complexity_delta"` // change in avg complexity
}
GraphDelta represents changes between two snapshots.
func CompareSnapshots ¶
func CompareSnapshots(old, cur *CodeGraphSnapshot) *GraphDelta
Compare compares two snapshots and returns the delta.
type GraphStats ¶
type GraphStats struct {
NodesByKind map[string]int `json:"nodes_by_kind"`
EdgesByKind map[string]int `json:"edges_by_kind"`
FilesByLang map[string]int `json:"files_by_lang"`
}
GraphStats holds statistics about the code graph.
type ModuleInfo ¶
type ModuleInfo struct {
Name string `json:"name"`
Path string `json:"path"`
Files int `json:"files"`
Functions int `json:"functions"`
Types int `json:"types"`
Imports []string `json:"imports"`
}
ModuleInfo represents a module/package in the snapshot.
type Node ¶
type Node struct {
ID string `json:"id"`
Kind NodeKind `json:"kind"`
Name string `json:"name"`
Path string `json:"path"`
Line int `json:"line"`
EndLine int `json:"end_line"`
TokenCount int `json:"token_count"`
Language string `json:"language"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
Node represents a symbol in the code graph.
type OTelCollector ¶
type OTelCollector struct {
// contains filtered or unexported fields
}
OTelCollector is a stub client for exporting span batches to an OpenTelemetry collector via OTLP/gRPC or OTLP/HTTP. The actual transport is out of scope; SendBatch validates the batch shape and returns nil on success so callers can code against the interface without a live collector.
func NewOTelCollector ¶
func NewOTelCollector(cfg OTelCollectorConfig) *OTelCollector
NewOTelCollector creates a collector client with the given config.
func (*OTelCollector) SendBatch ¶
func (c *OTelCollector) SendBatch(_ context.Context, batch *SpanBatch) error
SendBatch validates that the batch is non-nil and non-empty, then returns nil. In a production implementation this would marshal the batch to OTLP protobuf and POST to the configured endpoint, honouring config.Timeout and config.RetryConfig.
type OTelCollectorConfig ¶
type OTelCollectorConfig struct {
Endpoint string `json:"endpoint"`
Insecure bool `json:"insecure"`
Timeout time.Duration `json:"timeout"`
BatchSize int `json:"batch_size"`
FlushInterval time.Duration `json:"flush_interval"`
RetryConfig RetryConfig `json:"retry_config"`
}
OTelCollectorConfig holds configuration for the OpenTelemetry collector client.
func DefaultOTelCollectorConfig ¶
func DefaultOTelCollectorConfig() OTelCollectorConfig
DefaultOTelCollectorConfig returns a config with sensible production defaults: endpoint localhost:4317, 5 s timeout, batches of 100 spans, flush every 10 s.
type OTelEvent ¶
type OTelEvent struct {
Name string `json:"name"`
Timestamp time.Time `json:"timestamp"`
Attributes map[string]string `json:"attributes,omitempty"`
}
OTelEvent represents a timed annotation attached to a span.
type OTelSpan ¶
type OTelSpan struct {
TraceID string `json:"trace_id"`
SpanID string `json:"span_id"`
ParentSpanID string `json:"parent_span_id,omitempty"`
Name string `json:"name"`
Status string `json:"status"`
StartTime time.Time `json:"start_time"`
EndTime time.Time `json:"end_time"`
Attributes map[string]string `json:"attributes,omitempty"`
Events []OTelEvent `json:"events,omitempty"`
}
OTelSpan is the in-process representation of an OpenTelemetry span.
func ConvertTranscriptToOTelSpan ¶
ConvertTranscriptToOTelSpan converts a generic transcript entry (as stored in full.jsonl or transcript.jsonl) into an OTelSpan. It recognises common field names used across agent transcript formats.
type RetryConfig ¶
type RetryConfig struct {
MaxRetries int `json:"max_retries"`
BackoffMultiplier float64 `json:"backoff_multiplier"`
InitialBackoff time.Duration `json:"initial_backoff"`
}
RetryConfig controls retry behaviour when exporting span batches.
type SnapshotStore ¶
type SnapshotStore struct {
// contains filtered or unexported fields
}
SnapshotStore manages code graph snapshots.
func NewSnapshotStore ¶
func NewSnapshotStore(path string) *SnapshotStore
NewSnapshotStore creates a new snapshot store.
func (*SnapshotStore) Load ¶
func (s *SnapshotStore) Load() (*CodeGraphSnapshot, error)
Load loads the most recent snapshot.
func (*SnapshotStore) Save ¶
func (s *SnapshotStore) Save(snapshot CodeGraphSnapshot) error
Save persists a snapshot to disk.
type SpanBatch ¶
type SpanBatch struct {
Spans []OTelSpan `json:"spans"`
BatchID string `json:"batch_id"`
CreatedAt time.Time `json:"created_at"`
}
SpanBatch groups spans for bulk export.
func NewSpanBatch ¶
func NewSpanBatch() *SpanBatch
NewSpanBatch creates a new, empty batch with a unique ID.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
trace
command
|
|
|
trace/cli
hook_registry.go provides hook command registration for agents.
|
hook_registry.go provides hook command registration for agents. |
|
trace/cli/agent
Package agent provides interfaces and types for integrating with coding agents.
|
Package agent provides interfaces and types for integrating with coding agents. |
|
trace/cli/agent/claudecode
Package claudecode implements the Agent interface for Claude Code.
|
Package claudecode implements the Agent interface for Claude Code. |
|
trace/cli/agent/codex
Package codex implements the Agent interface for OpenAI's Codex CLI.
|
Package codex implements the Agent interface for OpenAI's Codex CLI. |
|
trace/cli/agent/copilotcli
Package copilotcli implements the Agent interface for GitHub Copilot CLI.
|
Package copilotcli implements the Agent interface for GitHub Copilot CLI. |
|
trace/cli/agent/cursor
Package cursor implements the Agent interface for Cursor.
|
Package cursor implements the Agent interface for Cursor. |
|
trace/cli/agent/external
Package external provides an adapter that bridges external agent binaries (discovered via PATH as trace-agent-<name>) to the agent.Agent interface.
|
Package external provides an adapter that bridges external agent binaries (discovered via PATH as trace-agent-<name>) to the agent.Agent interface. |
|
trace/cli/agent/factoryaidroid
Package factoryaidroid implements the Agent interface for Factory AI Droid.
|
Package factoryaidroid implements the Agent interface for Factory AI Droid. |
|
trace/cli/agent/geminicli
Package geminicli implements the Agent interface for Gemini CLI.
|
Package geminicli implements the Agent interface for Gemini CLI. |
|
trace/cli/agent/opencode
Package opencode implements the Agent interface for OpenCode.
|
Package opencode implements the Agent interface for OpenCode. |
|
trace/cli/agent/pi
Package pi implements the Agent interface for the pi coding agent (https://github.com/earendil-works/pi-mono).
|
Package pi implements the Agent interface for the pi coding agent (https://github.com/earendil-works/pi-mono). |
|
trace/cli/agent/pi/pijsonl
Package pijsonl provides shared parsing primitives for Pi's session JSONL format.
|
Package pijsonl provides shared parsing primitives for Pi's session JSONL format. |
|
trace/cli/agent/skilldiscovery
Package skilldiscovery holds the per-agent registries (curated built-ins, install hints) and the keyword match helper that the `trace review` picker uses to discover review-adjacent skills.
|
Package skilldiscovery holds the per-agent registries (curated built-ins, install hints) and the keyword match helper that the `trace review` picker uses to discover review-adjacent skills. |
|
trace/cli/agent/spawn
Package spawn provides the Spawner interface used by both `entire review` and `trace investigate` to start an agent process non-interactively.
|
Package spawn provides the Spawner interface used by both `entire review` and `trace investigate` to start an agent process non-interactively. |
|
trace/cli/agent/testutil
Package testutil provides shared test utilities for agent packages.
|
Package testutil provides shared test utilities for agent packages. |
|
trace/cli/agent/vogon
Package vogon implements the Agent interface for a deterministic test agent used as an E2E canary.
|
Package vogon implements the Agent interface for a deterministic test agent used as an E2E canary. |
|
trace/cli/agentlaunch
Package agentlaunch is the shared "launch a normal coding agent session with a composed prompt" helper, used by `entire review --fix` and `trace investigate fix`.
|
Package agentlaunch is the shared "launch a normal coding agent session with a composed prompt" helper, used by `entire review --fix` and `trace investigate fix`. |
|
trace/cli/benchutil
Package benchutil provides test fixture helpers for CLI benchmarks.
|
Package benchutil provides test fixture helpers for CLI benchmarks. |
|
trace/cli/checkpoint
Package checkpoint provides types and interfaces for checkpoint storage.
|
Package checkpoint provides types and interfaces for checkpoint storage. |
|
trace/cli/checkpoint/id
Package id provides the CheckpointID type for identifying checkpoints.
|
Package id provides the CheckpointID type for identifying checkpoints. |
|
trace/cli/execx
Package execx provides explicit helpers for spawning subprocesses with a chosen TTY attachment mode, replacing env-var signalling with real OS state.
|
Package execx provides explicit helpers for spawning subprocesses with a chosen TTY attachment mode, replacing env-var signalling with real OS state. |
|
trace/cli/gitexec
Package gitexec runs the git CLI from inside the codebase.
|
Package gitexec runs the git CLI from inside the codebase. |
|
trace/cli/gitremote
Package gitremote provides general-purpose git remote URL utilities: parsing, resolving, and redacting remote URLs.
|
Package gitremote provides general-purpose git remote URL utilities: parsing, resolving, and redacting remote URLs. |
|
trace/cli/interactive
Package interactive provides TTY-related helpers shared between the cli and strategy packages without inducing an import cycle (strategy cannot import cli).
|
Package interactive provides TTY-related helpers shared between the cli and strategy packages without inducing an import cycle (strategy cannot import cli). |
|
trace/cli/internal/flock
Package flock provides a small cross-process advisory-lock primitive built on POSIX flock (Unix) / LockFileEx (Windows).
|
Package flock provides a small cross-process advisory-lock primitive built on POSIX flock (Unix) / LockFileEx (Windows). |
|
trace/cli/investigate
Package investigate contains the env-var contract between `entire investigate` (which spawns the agent process) and the lifecycle hook (which adopts the session), plus the persisted run state for resuming an investigation.
|
Package investigate contains the env-var contract between `entire investigate` (which spawns the agent process) and the lifecycle hook (which adopts the session), plus the persisted run state for resuming an investigation. |
|
trace/cli/jsonutil
Package jsonutil provides JSON utilities with consistent formatting.
|
Package jsonutil provides JSON utilities with consistent formatting. |
|
trace/cli/lockfile
Package lockfile provides cross-process file locks.
|
Package lockfile provides cross-process file locks. |
|
trace/cli/logging
Package logging provides structured logging for the Trace CLI using slog.
|
Package logging provides structured logging for the Trace CLI using slog. |
|
trace/cli/mdrender
Package mdrender renders markdown to terminal-styled output using the shared trace CLI palette (orange H1, cyan H2, indigo H3, plus chroma syntax highlighting).
|
Package mdrender renders markdown to terminal-styled output using the shared trace CLI palette (orange H1, cyan H2, indigo H3, plus chroma syntax highlighting). |
|
trace/cli/osroot
Package osroot provides traversal-resistant file I/O helpers built on os.Root (Go 1.24+).
|
Package osroot provides traversal-resistant file I/O helpers built on os.Root (Go 1.24+). |
|
trace/cli/provenance
Package provenance owns the env-var contract that lets the lifecycle hook recognize a spawned agent process as part of `entire review` or `entire investigate`.
|
Package provenance owns the env-var contract that lets the lifecycle hook recognize a spawned agent process as part of `entire review` or `entire investigate`. |
|
trace/cli/recap
Package recap contains the server-backed data types and static renderer behind `trace recap`.
|
Package recap contains the server-backed data types and static renderer behind `trace recap`. |
|
trace/cli/review
Package review — see env.go for package-level rationale.
|
Package review — see env.go for package-level rationale. |
|
trace/cli/review/types
Package types defines the per-agent abstraction interfaces for `trace review`.
|
Package types defines the per-agent abstraction interfaces for `trace review`. |
|
trace/cli/search
Package search provides search functionality via the Trace search service.
|
Package search provides search functionality via the Trace search service. |
|
trace/cli/settings
Package settings provides configuration loading for Trace.
|
Package settings provides configuration loading for Trace. |
|
trace/cli/strategy
Package strategy provides the manual-commit strategy for managing Claude Code session changes via shadow branches and checkpoint condensation.
|
Package strategy provides the manual-commit strategy for managing Claude Code session changes via shadow branches and checkpoint condensation. |
|
trace/cli/stringutil
Package stringutil provides UTF-8 safe string manipulation utilities.
|
Package stringutil provides UTF-8 safe string manipulation utilities. |
|
trace/cli/summarize
Package summarize provides AI-powered summarization of development sessions.
|
Package summarize provides AI-powered summarization of development sessions. |
|
trace/cli/testutil
Package testutil provides shared test utilities for both integration and e2e tests.
|
Package testutil provides shared test utilities for both integration and e2e tests. |
|
trace/cli/trail
Package trail provides types and helpers for managing trail metadata.
|
Package trail provides types and helpers for managing trail metadata. |
|
trace/cli/trailers
Package trailers provides parsing and formatting for Trace commit message trailers.
|
Package trailers provides parsing and formatting for Trace commit message trailers. |
|
trace/cli/transcript
Package transcript provides shared types and utilities for parsing JSONL transcripts.
|
Package transcript provides shared types and utilities for parsing JSONL transcripts. |
|
trace/cli/transcript/compact
Package compact converts full.jsonl transcripts into a normalized, compact transcript.jsonl format.
|
Package compact converts full.jsonl transcripts into a normalized, compact transcript.jsonl format. |
|
trace/cli/tuiutil
Package tuiutil hosts width-aware text helpers for fixed-width TUI dashboards: ANSI/control-char stripping, display-width-based truncation and padding, and a compact duration formatter.
|
Package tuiutil hosts width-aware text helpers for fixed-width TUI dashboards: ANSI/control-char stripping, display-width-based truncation and padding, and a compact duration formatter. |
|
trace/cli/uiform
Package uiform builds huh forms wired to Trace's standard theme and accessibility behavior.
|
Package uiform builds huh forms wired to Trace's standard theme and accessibility behavior. |
|
trace/cli/validation
Package validation provides input validation functions for the Trace CLI.
|
Package validation provides input validation functions for the Trace CLI. |
|
trace/cli/versioninfo
Package versioninfo exposes the trace CLI version metadata.
|
Package versioninfo exposes the trace CLI version metadata. |
|
e2e
|
|
|
bootstrap
command
Package main provides a pre-test bootstrap command that runs agent-specific setup (auth config, warmup) before E2E tests.
|
Package main provides a pre-test bootstrap command that runs agent-specific setup (auth config, warmup) before E2E tests. |
|
cmd/testreport
command
|
|
|
vogon
command
vogon is a deterministic agent binary for E2E canary tests.
|
vogon is a deterministic agent binary for E2E canary tests. |