Documentation
¶
Overview ¶
Package tracing is part of the GoFastr harness.
See docs/harness-architecture.md § Logging (traces).
Package tracing emits W3C trace-context-shaped span trees per turn.
Span trees are written as JSON files at ~/.local/state/gofastr/harness/traces/<SessionID>/<TraceID>.json so the user can pipe them into a tool of their choice (jq, Jaeger import, etc.) without the harness pulling in a tracing library.
Span hierarchy mirrors the agent loop:
turn (root span) ├── request-middleware-chain ├── provider.chat │ └── stream-collect ├── tool-call (one span per dispatch) │ ├── permission-gate │ ├── sandbox-wrap │ └── tool.run └── persist-events
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoRecorder = errors.New("tracing: no recorder bound")
ErrNoRecorder is returned when API calls expect a recorder bound to a context but none is present.
Functions ¶
func TraceContextHeader ¶
TraceContextHeader returns the W3C `traceparent` header value for the given span: `00-<TraceID>-<SpanID>-01` (sampled).
Useful when the harness calls out to external services that understand W3C trace context (so a Copilot or OpenRouter request can be correlated back to the harness turn).
Types ¶
type Recorder ¶
type Recorder struct {
// contains filtered or unexported fields
}
Recorder collects spans for one turn and writes the trace to disk when Done is called.
func NewRecorder ¶
NewRecorder constructs a Recorder rooted at `dir`. The actual file is written to <dir>/<SessionID>/<TraceID>.json on Done.
type Span ¶
type Span struct {
TraceID string `json:"trace_id"`
SpanID string `json:"span_id"`
ParentID string `json:"parent_id,omitempty"`
Name string `json:"name"`
StartedAt time.Time `json:"started_at"`
EndedAt time.Time `json:"ended_at"`
DurationNS int64 `json:"duration_ns"`
Status string `json:"status,omitempty"` // "ok" | "error"
Attributes map[string]any `json:"attributes,omitempty"`
}
Span is one node in the trace tree.
type Trace ¶
type Trace struct {
TraceID string `json:"trace_id"`
SessionID string `json:"session_id"`
StartedAt time.Time `json:"started_at"`
EndedAt time.Time `json:"ended_at"`
Spans []Span `json:"spans"`
}
Trace is one full per-turn span tree.
Source Files