trace

Documentation

Overview

Package trace records optional, privacy-preserving tool-call summaries.

Index

• type ErrorKind
• type Event
• type Record
• type Summary
• type ToolSummary
• type Tracer
  • func Init() (*Tracer, error)
  • func NewWithBaseDir(baseDir string) (*Tracer, error)
  • func (t *Tracer) Close() error
  • func (t *Tracer) Record(event Event) error
  • func (t *Tracer) Summary() (Summary, error)

Types

type ErrorKind

type ErrorKind string

ErrorKind is a bounded failure category. It never contains a raw error.

const (
	// ErrorNone indicates that an operation completed without an error.
	ErrorNone ErrorKind = ""
	// ErrorInvalidInput indicates invalid caller input.
	ErrorInvalidInput ErrorKind = "invalid_input"
	// ErrorCancelled indicates caller cancellation.
	ErrorCancelled ErrorKind = "cancelled"
	// ErrorDeadline indicates an operation deadline.
	ErrorDeadline ErrorKind = "deadline"
	// ErrorSubprocess indicates a subprocess failure.
	ErrorSubprocess ErrorKind = "subprocess"
	// ErrorAnalysis indicates an analyzer failure.
	ErrorAnalysis ErrorKind = "analysis"
	// ErrorInternal indicates an unexpected internal failure.
	ErrorInternal ErrorKind = "internal"
)

type Event

type Event struct {
	Tool               string
	Args               any
	Duration           time.Duration
	PackagesLoad       time.Duration
	Analysis           time.Duration
	FindingsBySeverity map[string]int
	AnalyzerDurations  map[string]time.Duration
	ResultSummary      string
	ErrorKind          ErrorKind
}

Event is the caller-facing trace interface. Args are hashed and never stored.

type Record

type Record struct {
	Timestamp           time.Time        `json:"ts"`
	Tool                string           `json:"tool"`
	ArgsHash            string           `json:"args_hash"`
	DurationMS          int64            `json:"duration_ms"`
	PackagesLoadMS      int64            `json:"packages_load_ms"`
	AnalysisMS          int64            `json:"analysis_ms"`
	FindingsBySeverity  map[string]int   `json:"findings_by_severity"`
	AnalyzerDurationsMS map[string]int64 `json:"analyzer_durations_ms"`
	ResultSummary       string           `json:"result_summary"`
	Error               bool             `json:"error"`
	ErrorKind           ErrorKind        `json:"error_kind"`
}

Record is the deliberately bounded on-disk representation.

type Summary

type Summary struct {
	Enabled           bool          `json:"enabled"`
	RecordsConsidered int           `json:"records_considered"`
	Truncated         bool          `json:"truncated"`
	Tools             []ToolSummary `json:"tools"`
}

Summary describes a bounded recent window from the current server run.

type ToolSummary

type ToolSummary struct {
	Tool          string `json:"tool"`
	Calls         int    `json:"calls"`
	ErrorCount    int    `json:"error_count"`
	P50DurationMS int64  `json:"p50_duration_ms"`
	P99DurationMS int64  `json:"p99_duration_ms"`
}

ToolSummary is a bounded aggregate for one tool in the current trace run.

type Tracer

type Tracer struct {
	// contains filtered or unexported fields
}

Tracer is safe for concurrent use. A zero Tracer is disabled.

func Init

func Init() (*Tracer, error)

Init reads AGENTIC_GO_TRACE once and uses the operating-system user cache.

func NewWithBaseDir

func NewWithBaseDir(baseDir string) (*Tracer, error)

NewWithBaseDir creates an enabled tracer beneath an explicit base directory. It exists so tests can exercise the same filesystem implementation locally.

func (*Tracer) Close

func (t *Tracer) Close() error

Close flushes and closes the trace file. It is safe to call more than once.

func (*Tracer) Record

func (t *Tracer) Record(event Event) error

Record appends one bounded JSONL event. It is a no-op when disabled or closed.

func (*Tracer) Summary

func (t *Tracer) Summary() (Summary, error)

Summary returns aggregate trace data without exposing arguments or raw records.