Documentation
¶
Index ¶
- Constants
- func ExportTrace(cfg ExportConfig, turns []trace.Turn, store *evaluation.Store) error
- func SpansToTurns(root *Span) []trace.Turn
- type ExportConfig
- type K8sReader
- type Receiver
- type Span
- type SpanStatus
- type SpanStore
- func (ss *SpanStore) Add(span *Span)
- func (ss *SpanStore) AssembleTree(traceID string) *Span
- func (ss *SpanStore) ConversationIDs() []string
- func (ss *SpanStore) GetByConversation(id string) *Span
- func (ss *SpanStore) GetSpans(traceID string) []*Span
- func (ss *SpanStore) HasData() bool
- func (ss *SpanStore) LastUpdate() time.Time
- func (ss *SpanStore) SubagentInfoBySession(sessionID string) subagent.Info
- func (ss *SpanStore) SubagentsBySession(sessionID string) []subagent.Info
- func (ss *SpanStore) TraceCount() int
Constants ¶
const DefaultPollInterval = 5 * time.Second
DefaultPollInterval is the time between successive polls to the remote OTel Collector.
Variables ¶
This section is empty.
Functions ¶
func ExportTrace ¶
func ExportTrace(cfg ExportConfig, turns []trace.Turn, store *evaluation.Store) error
ExportTrace sends trace turns and annotations as OTLP/HTTP spans to the configured endpoint. Each turn becomes a child span under a session root span. Tool calls become grandchild spans. Annotations become span attributes.
func SpansToTurns ¶
SpansToTurns converts a span tree (from the OTEL receiver) into trace.Turn slices that the current TUI can render.
Handles two data formats:
- Claude Code log events: flat events with prompt.id, grouped into turns
- Codex/Gemini trace spans: hierarchical spans where each child is a turn
Auto-detects the format by checking for prompt.id attributes.
Types ¶
type ExportConfig ¶
type ExportConfig struct {
Endpoint string // e.g., "localhost:5001" (MLflow) or "localhost:4318" (collector)
Insecure bool // true for HTTP (no TLS)
SessionID string // session identifier
Provider string // "claude", "codex", "gemini"
ExperimentID string // MLflow experiment ID (required by MLflow OTLP endpoint)
Headers map[string]string // extra HTTP headers
// Session-level evaluation metadata (from .meta.json sidecar)
Annotation string // achieved/partial/failed/abandoned
FailureModes []string // failure-mode tags
Note string // free-text rationale
}
ExportConfig holds the configuration for OTEL export.
type K8sReader ¶ added in v0.7.0
type K8sReader struct {
// contains filtered or unexported fields
}
K8sReader connects to a remote OTel Collector and imports spans into the local SpanStore. It periodically fetches new spans and merges them with locally-collected data. Only instantiated when config.Kubernetes.OTELEndpoint is set.
func NewK8sReader ¶ added in v0.7.0
NewK8sReader creates a new K8sReader that will poll the given endpoint for remote agent traces and merge them into store.
func (*K8sReader) Start ¶ added in v0.7.0
Start begins polling the remote OTel Collector in a background goroutine. Non-blocking. Returns an error if the reader is already running.
type Receiver ¶
type Receiver struct {
// contains filtered or unexported fields
}
Receiver is an OTLP/HTTP trace receiver that listens for incoming spans from Claude Code, Codex CLI, Gemini CLI, or any OTEL-instrumented agent. It stores spans in a SpanStore for the TUI to display.
func NewReceiver ¶
NewReceiver creates a new OTLP/HTTP receiver.
func NewReceiverWithKeys ¶ added in v0.5.0
NewReceiverWithKeys creates a new OTLP/HTTP receiver with per-service subagent attribute keys for automatic extraction.
func (*Receiver) Start ¶
Start begins listening for OTLP/HTTP trace data on the configured port. Non-blocking -- runs the server in a goroutine.
type Span ¶
type Span struct {
SpanID string
TraceID string
ParentID string // empty for root spans
Name string // e.g., "invoke_agent", "chat", "execute_tool Read"
Start time.Time
End time.Time
Status SpanStatus
Attrs map[string]any // gen_ai.* attributes by OTEL convention names
Children []*Span
// aimux extensions (not in OTEL spec)
Label string // GOOD/BAD/WASTE annotation
Note string // annotation rationale
Subagent subagent.Info
}
Span is aimux's internal span representation, using OTEL GenAI semantic convention attribute names but as a simple data struct (not the OTEL SDK interface which is write-only). Supports hierarchy and aimux extensions.
func (*Span) AttrFloat64 ¶
AttrFloat64 returns a span attribute as float64, or 0 if not set. Handles string-encoded numbers (Claude Code sends cost_usd as string).
type SpanStatus ¶
type SpanStatus int
SpanStatus represents the outcome of a span.
const ( StatusOK SpanStatus = iota StatusError StatusUnset )
type SpanStore ¶
type SpanStore struct {
// contains filtered or unexported fields
}
SpanStore holds received OTEL spans in memory, indexed for fast lookup by session/conversation ID. Thread-safe.
func (*SpanStore) Add ¶
Add inserts a span into the store. If it has a conversation ID attribute, it's also indexed by conversation.
func (*SpanStore) AssembleTree ¶
AssembleTree builds parent-child relationships for all spans in a trace. Call after all spans for a trace have been added.
func (*SpanStore) ConversationIDs ¶
ConversationIDs returns all conversation/session IDs in the store.
func (*SpanStore) GetByConversation ¶
GetByConversation returns the root span tree for a conversation/session ID.
func (*SpanStore) LastUpdate ¶
LastUpdate returns when data was last received.
func (*SpanStore) SubagentInfoBySession ¶ added in v0.5.0
SubagentInfoBySession returns the subagent identity for a session ID.
func (*SpanStore) SubagentsBySession ¶ added in v0.5.0
SubagentsBySession returns all distinct subagent identities seen in OTEL events for a session. Used to create virtual agent entries for in-process subagents that don't have their own PID.
func (*SpanStore) TraceCount ¶
TraceCount returns the number of distinct trace IDs stored.