observers

type DebugFrameFilter struct {
	// Frame is an instance of the frame type to log; its type is what is
	// matched, not its contents.
	Frame frames.Frame
	// Match, when set, logs the frame only where the processor at Endpoint
	// satisfies it. Leave it nil to log the frame wherever it travels.
	Match func(processor.Processor) bool
	// Endpoint is the end of the handover Match decides on.
	Endpoint FrameEndpoint
}

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

type DebugLogConfig struct {
	// Logger is the destination; slog.Default() when nil.
	Logger *slog.Logger
	// Frames selects what to log. An empty list logs every frame, which on a
	// real pipeline is a great many.
	Frames []DebugFrameFilter
	// ExcludeFields names the frame fields left out of the log. A nil slice
	// leaves out the binary payloads (Audio, Image, Images); an empty non-nil
	// slice leaves out nothing.
	ExcludeFields []string
}

type FrameEndpoint int

type FunctionCallMetrics struct {
	// FunctionName is the name of the tool that was called.
	FunctionName string
	// StartTime is the wall-clock time the call started at.
	StartTime time.Time
	// Duration is the time from the call starting to its result arriving.
	Duration time.Duration
}

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

type LLMLogConfig struct {
	// Logger is the destination; slog.Default() when nil.
	Logger *slog.Logger
}

type LatencyBreakdown struct {
	// TTFB is what each service took to produce anything at all, in the order
	// the measurements were reported.
	TTFB []TTFBBreakdown
	// TextAggregation is the first text-aggregation measurement of the cycle,
	// which is what grouping the model's tokens into sentences cost before
	// synthesis could start. It is nil when none was reported.
	TextAggregation *TextAggregationBreakdown
	// UserTurnStart is when the user's turn ended in the audio: the moment the
	// speech itself stopped, before the detector had confirmed it. The zero
	// value means no VAD stop was observed.
	UserTurnStart time.Time
	// UserTurn is how long releasing the turn took from that moment: the
	// detector's silence window, the transcriber finalizing, and any wait on an
	// end-of-turn analyzer. It is nil when the turn was never released, which is
	// what a pipeline with no turn analyzer looks like.
	UserTurn *time.Duration
	// FunctionCalls is how long each tool call of the cycle took. It is empty
	// when the reply made none.
	FunctionCalls []FunctionCallMetrics
}

type LatencyConfig struct {
	// MaxFrames is how many recent frame ids the observer remembers to
	// recognize one it has already counted; 0 uses 100.
	MaxFrames int
	// OnLatency is called with the time from the user stopping speaking to the
	// bot starting: the user-perceived response latency.
	OnLatency func(d time.Duration)
	// OnBreakdown is called with the per-service account of the same cycle,
	// alongside every latency the observer reports. It is empty of measurements
	// unless the pipeline collects metrics.
	OnBreakdown func(b LatencyBreakdown)
	// OnFirstBotSpeechLatency is called once, with the time from the client
	// connecting to the bot first speaking. It is not called at all when the
	// user speaks first: the figure means the greeting was slow, and there is no
	// greeting to measure once the conversation has started without one.
	OnFirstBotSpeechLatency func(d time.Duration)
}

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

type MetricsLogConfig struct {
	// Logger is the destination; slog.Default() when nil.
	Logger *slog.Logger
	// Include selects the kinds of measurement to log, given as instances of
	// the frames.MetricsData types wanted. An empty list logs every kind.
	Include []frames.MetricsData
}

type ProcessorStartupTiming struct {
	// ProcessorName is the name of the processor.
	ProcessorName string
	// StartOffset is how long after the StartFrame entered the pipeline this
	// processor began starting.
	StartOffset time.Duration
	// Duration is what the processor cost to get ready: its setup and its start
	// together. It connects while it is set up, and starting is whatever is left
	// to do once it has.
	Duration time.Duration
	// SetupDuration is how long the processor's setup took, which is the part of
	// Duration spent connecting.
	SetupDuration time.Duration
}

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

type StartupTimingConfig struct {
	// Track selects the processors to measure. When nil every processor is
	// measured except the pipeline plumbing: the pipelines themselves, and the
	// sources they wrap the head of their chains in.
	Track func(processor.Processor) bool
	// OnStartupTimingReport is called once, when the pipeline has started, with
	// what each processor cost. It is not called when nothing was measured.
	OnStartupTimingReport func(r StartupTimingReport)
	// OnTransportTimingReport is called once, when the first client connects,
	// with how long the transport took to get there.
	OnTransportTimingReport func(r TransportTimingReport)
}

type StartupTimingReport struct {
	// StartTime is the wall-clock time at which the pipeline began setting up.
	StartTime time.Time
	// TotalDuration is the wall-clock time from the pipeline starting to set up
	// until it had started. Processors are set up concurrently, so it is the
	// span rather than the sum of what each of them cost.
	TotalDuration time.Duration
	// ProcessorTimings is what each processor cost, in the order the StartFrame
	// left them.
	ProcessorTimings []ProcessorStartupTiming
}

type TTFBBreakdown struct {
	// Processor is the name of the processor that reported it.
	Processor string
	// Model is the model it is attributed to, "" when unknown.
	Model string
	// StartTime is the wall-clock time the measurement started at.
	StartTime time.Time
	// Duration is the measured time to first byte.
	Duration time.Duration
}

type TextAggregationBreakdown struct {
	// Processor is the name of the processor that reported it.
	Processor string
	// StartTime is the wall-clock time the measurement started at.
	StartTime time.Time
	// Duration is the measured aggregation time.
	Duration time.Duration
}

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

type TranscriptionLogConfig struct {
	// Logger is the destination; slog.Default() when nil.
	Logger *slog.Logger
}

type TransportTimingReport struct {
	// StartTime is the wall-clock time at which the pipeline began setting up.
	StartTime time.Time
	// BotConnected is how long after the pipeline began setting up the bot
	// itself joined
	// the session. It is nil on a transport that never reports the bot joining,
	// which is every transport that is not an SFU.
	BotConnected *time.Duration
	// ClientConnected is how long after the pipeline began setting up the first
	// remote participant connected.
	ClientConnected time.Duration
}

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

type TurnTraceConfig struct {
	// Tracing is the pipeline's tracing context, which the observer writes as
	// the conversation and its turns begin and end. Required: it is what the
	// services read to parent their spans to the turn being spoken.
	Tracing *tracing.TracingContext
	// ConversationID names the conversation; empty generates one.
	ConversationID string
	// Attributes are set on the conversation span on top of the ones the
	// observer sets itself, and are where the keys a trace backend reads from
	// the root span belong (a session id, a user id, tags).
	Attributes []attribute.KeyValue
}

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

type TurnTrackingConfig struct {
	// MaxFrames is how many recent frame ids the observer remembers to
	// recognize one it has already counted; 0 uses 100.
	MaxFrames int
	// TurnEndTimeout is how long after the bot stops speaking a turn ends; 0 uses
	// 2.5s. The delay lets a turn survive a brief gap between bot utterances (an
	// HTTP TTS boundary, a function call) without splitting into two turns.
	TurnEndTimeout time.Duration
	// OnTurnStarted is called when a turn begins, with the 1-based turn number.
	OnTurnStarted func(turn int)
	// OnTurnEnded is called when a turn ends, with the turn number, its duration,
	// and whether it was cut short by an interruption.
	OnTurnEnded func(turn int, duration time.Duration, interrupted bool)
}

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