trace

package
v0.15.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 25, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package trace provides execution tracing and audit logging.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func WithParentSpan added in v0.3.0 

func WithParentSpan(ctx context.Context, spanID string) context.Context

WithParentSpan adds a parent span ID to the context.

func WithTraceID added in v0.3.0 

func WithTraceID(ctx context.Context, traceID string) context.Context

WithTraceID adds a trace ID to the context.

Types

type Collector 

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

Collector records traces and audit events.

func NewCollector 

func NewCollector(store storage.Storage) *Collector

func (*Collector) Audit 

func (c *Collector) Audit(ctx context.Context, sessionID, actor, action, resource string) error

Audit records a security audit event.

func (*Collector) EndSpan 

func (c *Collector) EndSpan(ctx context.Context, t *storage.Trace, output any, errMsg string) error

EndSpan completes a trace span.

func (*Collector) StartSpan 

func (c *Collector) StartSpan(ctx context.Context, sessionID, name, kind string) (*storage.Trace, error)

StartSpan begins a new trace span.

type NoopSpanExporter added in v0.4.0 

type NoopSpanExporter struct{}

NoopSpanExporter discards spans. It is the default when no OTLP endpoint is configured.

func (NoopSpanExporter) ExportSpans added in v0.4.0 

func (NoopSpanExporter) ExportSpans(context.Context, []*OTelSpan) error

func (NoopSpanExporter) Shutdown added in v0.4.0 

func (NoopSpanExporter) Shutdown(context.Context) error

type OTLPSpanExporter added in v0.4.0 

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

OTLPSpanExporter exports spans to an OTLP/HTTP endpoint using the JSON encoding of the OpenTelemetry trace protocol (ExportTraceServiceRequest).

func NewOTLPSpanExporter added in v0.4.0 

func NewOTLPSpanExporter(endpoint string) *OTLPSpanExporter

NewOTLPSpanExporter creates an exporter that POSTs to "<endpoint>/v1/traces".

func (*OTLPSpanExporter) ExportSpans added in v0.4.0 

func (e *OTLPSpanExporter) ExportSpans(ctx context.Context, spans []*OTelSpan) error

func (*OTLPSpanExporter) Shutdown added in v0.4.0 

func (e *OTLPSpanExporter) Shutdown(context.Context) error

func (*OTLPSpanExporter) WithHTTPClient added in v0.4.0 

func (e *OTLPSpanExporter) WithHTTPClient(c *http.Client) *OTLPSpanExporter

WithHTTPClient overrides the HTTP client (useful for tests).

func (*OTLPSpanExporter) WithHeader added in v0.4.0 

func (e *OTLPSpanExporter) WithHeader(k, v string) *OTLPSpanExporter

WithHeader adds a header sent with each export request.

type OTelCollector added in v0.3.0 

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

OTelCollector collects OpenTelemetry-compatible spans and exports them to a configured endpoint. It supports proper parent-child relationships and attributes for agent, graph, tool, and model operations.

func NewOTelCollector added in v0.3.0 

func NewOTelCollector(endpoint string) *OTelCollector

NewOTelCollector creates a new OTel-compatible span collector. endpoint is the OTLP endpoint to export spans to (empty = no-op export, spans are still collected in-memory and available via Spans/Flush). A non-empty endpoint wires a real OTLP/HTTP exporter.

func NewOTelCollectorWithExporter added in v0.4.0 

func NewOTelCollectorWithExporter(exporter SpanExporter) *OTelCollector

NewOTelCollectorWithExporter creates a collector with a caller-supplied exporter (e.g. a stdout exporter for local debugging, or a fake in tests).

func (*OTelCollector) EndSpan added in v0.3.0 

func (c *OTelCollector) EndSpan(span *OTelSpan, err error)

EndSpan completes a span, setting its end time and status.

func (*OTelCollector) Export added in v0.4.0 

func (c *OTelCollector) Export(ctx context.Context) error

Export sends all currently collected spans to the configured exporter and clears the in-memory buffer. With the default (no-op) exporter this only drains the buffer and never touches the network.

func (*OTelCollector) Flush added in v0.3.0 

func (c *OTelCollector) Flush() []*OTelSpan

Flush returns all spans and clears the collector.

func (*OTelCollector) SetEnabled added in v0.3.0 

func (c *OTelCollector) SetEnabled(enabled bool)

SetEnabled enables or disables span collection.

func (*OTelCollector) Spans added in v0.3.0 

func (c *OTelCollector) Spans() []*OTelSpan

Spans returns all collected spans.

func (*OTelCollector) StartSpan added in v0.3.0 

func (c *OTelCollector) StartSpan(ctx context.Context, name, kind string, attrs map[string]any) *OTelSpan

StartSpan begins a new OTel span with the given name and kind.

type OTelSpan added in v0.3.0 

type OTelSpan struct {
	TraceID    string         `json:"trace_id"`
	SpanID     string         `json:"span_id"`
	ParentID   string         `json:"parent_id,omitempty"`
	Name       string         `json:"name"`
	Kind       string         `json:"kind"` // agent, graph, tool, model
	Attributes map[string]any `json:"attributes,omitempty"`
	StartTime  time.Time      `json:"start_time"`
	EndTime    time.Time      `json:"end_time,omitempty"`
	Status     string         `json:"status"` // ok, error, unset
	Events     []SpanEvent    `json:"events,omitempty"`
}

OTelSpan represents an OpenTelemetry-compatible span.

func (*OTelSpan) AddEvent added in v0.3.0 

func (span *OTelSpan) AddEvent(name string, attrs map[string]any)

AddEvent adds a timestamped event to a span.

type SpanEvent added in v0.3.0 

type SpanEvent struct {
	Name       string         `json:"name"`
	Timestamp  time.Time      `json:"timestamp"`
	Attributes map[string]any `json:"attributes,omitempty"`
}

SpanEvent is a timestamped annotation on a span.

type SpanExporter added in v0.4.0 

type SpanExporter interface {
	// ExportSpans sends a batch of spans. It should honor ctx cancellation.
	ExportSpans(ctx context.Context, spans []*OTelSpan) error
	// Shutdown flushes and releases any resources.
	Shutdown(ctx context.Context) error
}

SpanExporter exports collected spans to a backend. Implementations must be safe for offline use: with no endpoint configured the collector uses a NoopSpanExporter so tests and disconnected runs never require a collector.

type StdoutSpanExporter added in v0.4.0 

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

StdoutSpanExporter writes each span batch as OTLP/JSON to an io.Writer, useful for local debugging without a collector.

func NewStdoutSpanExporter added in v0.4.0 

func NewStdoutSpanExporter(w io.Writer) *StdoutSpanExporter

NewStdoutSpanExporter creates a stdout-style exporter writing to w.

func (*StdoutSpanExporter) ExportSpans added in v0.4.0 

func (e *StdoutSpanExporter) ExportSpans(_ context.Context, spans []*OTelSpan) error

func (*StdoutSpanExporter) Shutdown added in v0.4.0 

func (e *StdoutSpanExporter) Shutdown(context.Context) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.