Documentation
¶
Overview ¶
Package trace implements the context-trace event log: an append-only JSONL record of everything that happened during an agent session, separate from the chatstore state layer. Design: docs/design/context-trace.md.
The package owns the envelope schema, event payload types, and the async Recorder. The Tracer interface that the engine holds lives in agent/hooks (agent/engine never imports dino; see design §3.2④). Recording points in the engine call Tracer.Record with an Event; the recorder fills the envelope.
Index ¶
- Constants
- func RenderText(events []TraceEvent) string
- func WriteJSONL(w io.Writer, events []TraceEvent) error
- type ChunkPayload
- type CompactionPayload
- type Config
- type ErrorPayload
- type Event
- type LLMCallEndPayload
- type LLMCallPayload
- type MemorySavePayload
- type Recorder
- type ReducedIteration
- type ReducedLLMCall
- type ReducedToolCall
- type ReducedTurn
- type Stats
- type ToolCallPayload
- type ToolErrorPayload
- type ToolResultPayload
- type TraceEvent
- type TurnEndPayload
- type TurnStartPayload
Constants ¶
const ( // Engine layer (recorded in agent/engine). EventTurnStart = "turn_start" // Payload: TurnStartPayload EventTurnEnd = "turn_end" // Payload: TurnEndPayload EventLLMCall = "llm_call" // Payload: LLMCallPayload EventLLMCallEnd = "llm_call_end" // Payload: LLMCallEndPayload EventLLMChunk = "llm_chunk" // Payload: ChunkPayload (default off) EventToolCall = "tool_call" // Payload: ToolCallPayload EventToolResult = "tool_result" // Payload: ToolResultPayload EventToolError = "tool_error" // Payload: ToolErrorPayload EventCompaction = "compaction" // Payload: CompactionPayload EventMemorySave = "memory_save" // Payload: MemorySavePayload EventError = "error" // Payload: ErrorPayload // dino orchestration layer (session Observer). EventOrchestration = "orchestration" // Payload: *session.Event )
Event type constants. Payload contract documented per constant.
const SchemaVersion = 1
SchemaVersion is the envelope schema version. Bump on semantic changes (required-field additions, meaning changes); adding optional fields does not bump.
Variables ¶
This section is empty.
Functions ¶
func RenderText ¶
func RenderText(events []TraceEvent) string
RenderText folds events into a readable conversation/tool sequence (design §6.2). It returns the rendered text and a trailing accounting line.
func WriteJSONL ¶
func WriteJSONL(w io.Writer, events []TraceEvent) error
WriteJSONL writes events as raw JSONL (debug output).
Types ¶
type ChunkPayload ¶
type ChunkPayload struct {
Content string `json:"content"`
}
ChunkPayload records merged chunk text (default off, §4.3).
type CompactionPayload ¶
type CompactionPayload struct {
BeforeCount int `json:"before_count"`
AfterCount int `json:"after_count"`
BudgetTokens int `json:"budget_tokens"`
SummaryFolded bool `json:"summary_folded,omitempty"`
HasSummary bool `json:"has_summary,omitempty"`
Mode string `json:"mode"` // "tail_only" | "three_phase" | "none"
}
CompactionPayload records history trimming / summary injection.
type Config ¶
type Config struct {
// Dir is the trace output directory. Empty falls back to DefaultConfig.Dir.
Dir string
// QueueSize is the events channel capacity. Record drops (non-blocking)
// once full, counting dropped_events.
QueueSize int
// FlushInterval is how often the writer goroutine flushes the bufio writer.
FlushInterval time.Duration
// BatchSize flushes when len(events) in the channel >= BatchSize.
BatchSize int
// CaptureFullMessages records the full llm_call Messages (default off:
// each message content is truncated).
CaptureFullMessages bool
// CaptureFullToolOutput records the full tool_result Output (default off:
// output is truncated with count fields).
CaptureFullToolOutput bool
// CaptureChunks records llm_chunk events (default off; high volume).
CaptureChunks bool
// MaxBytes is the per-file size cap before rotation (default 512MB).
MaxBytes int64
// MessageContentMaxLen caps each llm_call message content when
// CaptureFullMessages is false. 0 = default 4096.
MessageContentMaxLen int
// ToolOutputMaxLen caps each tool_result output when
// CaptureFullToolOutput is false. 0 = default 60000.
ToolOutputMaxLen int
}
Config controls the recorder's write behaviour. All fields have safe defaults via DefaultConfig.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a Config with the design's default values.
type ErrorPayload ¶
type ErrorPayload struct {
Message string `json:"message"`
StopCause types.AgentStopCause `json:"stop_cause,omitempty"`
}
ErrorPayload records a stream/iteration error.
type Event ¶
type Event struct {
Type string
Iteration *int
ThreadID string
ParentTraceID string
Payload any // must be json.Marshal-able
}
Event is the minimal event passed by engine/dino to the recorder; the recorder fills the envelope fields.
type LLMCallEndPayload ¶
type LLMCallEndPayload struct {
Usage types.Usage `json:"usage"`
DurationMS int64 `json:"duration_ms"`
OutputLen int `json:"output_len"`
Reasoning string `json:"reasoning,omitempty"`
ToolCalls []types.ToolCallRequest `json:"tool_calls,omitempty"`
HasError bool `json:"has_error,omitempty"`
Error string `json:"error,omitempty"`
}
LLMCallEndPayload records one model call end with usage/duration.
type LLMCallPayload ¶
type LLMCallPayload struct {
Messages []types.Message `json:"messages"` // engine's actual input (volume-controlled, §4.3)
Tools []string `json:"tools,omitempty"`
EstTokensIn int `json:"est_tokens_in"` // types.RoughTokenEstimate
}
LLMCallPayload records one model call start (messages captured at call time).
type MemorySavePayload ¶
type MemorySavePayload struct {
InputRole string `json:"input_role"`
CompressTriggered bool `json:"compress_triggered"`
Reason string `json:"reason,omitempty"` // "threshold" | "compact_after_turns" | ""
}
MemorySavePayload records a memory save / compression trigger.
type Recorder ¶
type Recorder struct {
// contains filtered or unexported fields
}
Recorder is a session-bound trace writer. It owns one events channel and one writer goroutine; Record is non-blocking (drops + counts when full), Flush synchronously drains + fsyncs, Close is idempotent.
Zero value is invalid; construct via NewRecorder. Recorder must not be copied after first use.
func NewRecorder ¶
NewRecorder creates a session-bound recorder. sessionID may contain '/' — the file name escapes it. Errors are returned when the directory cannot be created or the file opened; callers should treat failure as "trace disabled" (never block the session).
func (*Recorder) Close ¶
Close drains the channel, flushes, fsyncs, and closes the file. Idempotent.
func (*Recorder) Flush ¶
Flush synchronously drains the channel and fsyncs the file, guaranteeing a completed turn is readable. Called at turn_end.
func (*Recorder) Record ¶
func (r *Recorder) Record(ev hooks.TraceEvent)
Record appends an event, non-blocking. It drops (and counts) when the channel is full — trace is a side channel and must never block the engine. It accepts hooks.TraceEvent (the engine's minimal event) and converts to the package's Event, so Recorder implements hooks.Tracer directly.
type ReducedIteration ¶
type ReducedIteration struct {
Index int `json:"index"`
LLMCalls []ReducedLLMCall `json:"llm_calls"`
ToolCalls []ReducedToolCall `json:"tool_calls"`
}
ReducedIteration groups one engine iteration's LLM calls and tool calls.
type ReducedLLMCall ¶
type ReducedLLMCall struct {
Output string `json:"output"`
Reasoning string `json:"reasoning,omitempty"`
Usage types.Usage `json:"usage"`
DurationMS int64 `json:"duration_ms"`
Tools []string `json:"tools,omitempty"`
Error string `json:"error,omitempty"`
}
ReducedLLMCall is one model call within an iteration.
type ReducedToolCall ¶
type ReducedToolCall struct {
ToolName string `json:"tool_name"`
ToolCallID string `json:"tool_call_id"`
Input any `json:"input"`
Output any `json:"output,omitempty"`
Error string `json:"error,omitempty"`
DurationMS int64 `json:"duration_ms"`
Cached bool `json:"cached,omitempty"`
Dangling bool `json:"dangling,omitempty"`
}
ReducedToolCall is one tool execution within an iteration (paired by tool_call_id; dangling results are marked).
type ReducedTurn ¶
type ReducedTurn struct {
TraceID string `json:"trace_id"`
SessionID string `json:"session_id"`
ThreadID string `json:"thread_id,omitempty"`
ParentTraceID string `json:"parent_trace_id,omitempty"`
Input string `json:"input"`
FinalOutput string `json:"final_output"`
Iterations []ReducedIteration `json:"iterations"`
Usage types.Usage `json:"usage"`
WallMS int64 `json:"wall_ms"`
StopCause string `json:"stop_cause,omitempty"`
Error string `json:"error,omitempty"`
}
ReducedTurn is the folded semantic graph for one trace_id (one agent execution). Design §6.3.
func Reduce ¶
func Reduce(events []TraceEvent) []*ReducedTurn
Reduce folds raw events into per-trace ReducedTurns.
type Stats ¶
type Stats struct {
// EventsRecorded is the number of events enqueued (never drops).
EventsRecorded int64
// EventsDropped counts non-blocking Record drops (channel full).
EventsDropped int64
// BytesWritten is the total payload bytes written to files.
BytesWritten int64
// RotationCount counts file rotations.
RotationCount int64
}
Stats exposes observable counters for diagnostics.
type ToolCallPayload ¶
type ToolCallPayload struct {
ToolName string `json:"tool_name"`
ToolCallID string `json:"tool_call_id"`
Input map[string]any `json:"input"`
StartWallMS int64 `json:"start_wall_ms"`
}
ToolCallPayload records tool execution start.
type ToolErrorPayload ¶
type ToolErrorPayload struct {
ToolName string `json:"tool_name"`
ToolCallID string `json:"tool_call_id"`
Error string `json:"error"`
DurationMS int64 `json:"duration_ms"`
}
ToolErrorPayload records a failed tool execution.
type ToolResultPayload ¶
type ToolResultPayload struct {
ToolName string `json:"tool_name"`
ToolCallID string `json:"tool_call_id"`
Output any `json:"output"`
DurationMS int64 `json:"duration_ms"`
Cached bool `json:"cached,omitempty"`
}
ToolResultPayload records a successful tool execution.
type TraceEvent ¶
type TraceEvent struct {
SchemaVersion int `json:"schema_version"`
Seq int64 `json:"seq"` // monotonic within file, from 1, atomically assigned
WallTimeUnixMS int64 `json:"wall_time_unix_ms"` // event enqueue time
TraceID string `json:"trace_id"` // one ExecuteStream/Execute call = one turn segment
SessionID string `json:"session_id"` // file ownership; subagent = parent session + thread suffix
TurnID int `json:"turn_id"` // monotonic turn order within session (recorder-assigned)
Iteration *int `json:"iteration,omitempty"` // engine iteration (llm_call/tool events carry it); nil = not iteration-grained
ThreadID string `json:"thread_id,omitempty"` // subagent hierarchy path (e.g. "/root/task_1")
ParentTraceID string `json:"parent_trace_id,omitempty"` // subagent provenance (parent turn's TraceID)
Type string `json:"type"` // event type (see constants)
Payload json.RawMessage `json:"payload"` // typed payload (see Payload* structs)
PayloadRef string `json:"payload_ref,omitempty"` // externalized payload path (default off, §4.4)
}
TraceEvent is the full envelope for one JSONL line (single envelope: partial replay is safe — each line is independently parseable).
func LoadTraces ¶
func LoadTraces(dir, session, traceID, threadID string) ([]TraceEvent, error)
LoadTraces reads all trace-<session>.jsonl (and .1 rotated) files under dir, filtering by optional session/trace/thread. Returns events sorted by seq.
type TurnEndPayload ¶
type TurnEndPayload struct {
Output string `json:"output"`
Usage types.Usage `json:"usage"`
Iterations int `json:"iterations"`
StopCause types.AgentStopCause `json:"stop_cause,omitempty"`
WallMS int64 `json:"wall_ms"` // turn wall clock
}
TurnEndPayload records the end of one agent execution.
type TurnStartPayload ¶
type TurnStartPayload struct {
Input types.AgentInput `json:"input"`
Model string `json:"model"`
SystemPromptLen int `json:"system_prompt_len"`
MaxIterations int `json:"max_iterations"`
ToolNames []string `json:"tool_names,omitempty"` // visible tool names (evidence)
}
TurnStartPayload records the beginning of one agent execution.
Source Files