Documentation
¶
Index ¶
- Constants
- func EnrichTurnsWithReplies(turns []trace.Turn, replies map[string]string)
- func ExportTrace(cfg ExportConfig, turns []trace.Turn, store *evaluation.Store) error
- func FetchSessionReplies(sandboxName, sessionID string) map[string]string
- func FetchSessionTurns(sandboxName, sessionID string) []trace.Turn
- func FlushTracker(store *SpanStore, dataDir string) error
- func ParseSessionReplies(data []byte) map[string]string
- func ParseSessionTurns(data []byte) []trace.Turn
- 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) TakeIdle(cutoff time.Time) map[string]*Span
- func (ss *SpanStore) TraceCount() int
- type ToolDetail
- type Tracker
- type TrackerData
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 EnrichTurnsWithReplies ¶ added in v0.13.0
EnrichTurnsWithReplies fills in OutputLines on turns that have a matching promptId in the replies map. The converter produces turns with promptId stored as the first UserLine's source — we match by scanning the OTEL span's prompt.id attribute via the turn's PromptID field.
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 FetchSessionReplies ¶ added in v0.13.0
FetchSessionReplies reads the Claude Code session JSONL from inside a remote sandbox and returns assistant reply text keyed by promptId. Returns nil (not an error) if the file doesn't exist yet or the exec fails — this is called on every trace-pane refresh and transient failures are expected.
func FetchSessionTurns ¶ added in v0.13.0
FetchSessionTurns reads the session JSONL from inside a sandbox and builds trace.Turn entries directly from it, without needing OTEL data. This is the fallback for the preview/trace pane when the OTEL store is empty (e.g., after an aimux restart).
func FlushTracker ¶ added in v0.13.0
FlushTracker writes tracker JSON for every session in the store, including totals saved by earlier compactions. Existing files are overwritten.
func ParseSessionReplies ¶ added in v0.13.0
ParseSessionReplies extracts assistant reply text from a Claude Code session JSONL file, keyed by the promptId of the preceding user message. Claude Code puts promptId on user entries but NOT on assistant entries, so we track the last-seen user promptId and assign the next assistant's text to it.
This is the primary source for model reply text in aimux's trace pane: Claude Code's OTEL telemetry does not emit assistant responses, but the session JSONL file (written to disk inside the sandbox) contains the full conversation transcript.
func ParseSessionTurns ¶ added in v0.13.0
ParseSessionTurns builds complete trace.Turn entries directly from a Claude Code session JSONL file, without needing any OTEL data. This is the fallback for the preview/trace pane when the OTEL store has no spans (e.g., after an aimux restart — the in-memory OTEL store is empty but the session file on the sandbox's disk is persistent).
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 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"
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, 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) SetBindAll ¶ added in v0.13.0
SetBindAll configures the receiver to listen on all interfaces (0.0.0.0) instead of localhost only. Required when remote sandboxes send OTEL data via host.openshell.internal.
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) TakeIdle ¶ added in v0.14.0
TakeIdle removes every session and trace with no span added since cutoff and returns the removed sessions' root spans by session ID (an aimux.session_id alias maps to the same root). Removal and return happen under one lock, so no span can arrive between reading and dropping.
func (*SpanStore) TraceCount ¶
TraceCount returns the number of distinct trace IDs stored.
type ToolDetail ¶ added in v0.13.0
type ToolDetail struct {
Tokens int `json:"tokens"`
Calls int `json:"calls"`
CostUSD float64 `json:"cost_usd,omitempty"`
}
ToolDetail holds per-tool token, call, and cost data.
type Tracker ¶ added in v0.14.0
type Tracker struct {
// contains filtered or unexported fields
}
Tracker writes per-session tracker JSON from a SpanStore and compacts idle sessions out of memory into saved state.
func NewTracker ¶ added in v0.14.0
NewTracker returns a Tracker writing to dataDir.
type TrackerData ¶ added in v0.13.0
type TrackerData struct {
Agents int `json:"agents"`
Tools int `json:"tools"`
MCP int `json:"mcp"`
Calls int `json:"calls"`
CostUSD float64 `json:"cost_usd,omitempty"`
ByTool map[string]ToolDetail `json:"by_tool,omitempty"`
Last string `json:"last,omitempty"`
}
TrackerData is the per-session JSON written to ~/.aimux/data/context/. The schema matches what claude-hud's context-breakdown.ts expects.