observability

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Mar 22, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package observability provides instrumentation interfaces for voice operations.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EmitEvent 

func EmitEvent(ctx context.Context, observer VoiceObserver, eventType EventType, callID, provider string, opts ...EventOption)

EmitEvent is a helper to emit events with common fields populated.

Types

type EventOption 

type EventOption func(*VoiceEvent)

EventOption configures a VoiceEvent.

func WithDirection 

func WithDirection(dir string) EventOption

WithDirection sets the call direction.

func WithDuration 

func WithDuration(d time.Duration) EventOption

WithDuration sets the call duration.

func WithError 

func WithError(err error) EventOption

WithError sets the error.

func WithFrom 

func WithFrom(from string) EventOption

WithFrom sets the caller ID.

func WithMetadata 

func WithMetadata(key string, value any) EventOption

WithMetadata adds metadata to the event.

func WithTo 

func WithTo(to string) EventOption

WithTo sets the called number.

type EventType 

type EventType string

EventType identifies the type of voice event. 

const (
	// EventCallInitiated is emitted when a call is started (outbound) or received (inbound).
	EventCallInitiated EventType = "call.initiated"

	// EventCallRinging is emitted when an outbound call starts ringing.
	EventCallRinging EventType = "call.ringing"

	// EventCallAnswered is emitted when a call is answered.
	EventCallAnswered EventType = "call.answered"

	// EventCallEnded is emitted when a call ends (normal hangup).
	EventCallEnded EventType = "call.ended"

	// EventCallFailed is emitted when a call fails.
	EventCallFailed EventType = "call.failed"

	// EventCallBusy is emitted when the line is busy.
	EventCallBusy EventType = "call.busy"

	// EventCallNoAnswer is emitted when there's no answer.
	EventCallNoAnswer EventType = "call.no_answer"
)

CallSystem lifecycle events. 

const (
	// EventMediaConnected is emitted when media streaming connects.
	EventMediaConnected EventType = "media.connected"

	// EventMediaDisconnected is emitted when media streaming disconnects.
	EventMediaDisconnected EventType = "media.disconnected"

	// EventMediaError is emitted on media streaming errors.
	EventMediaError EventType = "media.error"
)

Media streaming events. 

const (
	// EventDTMFReceived is emitted when DTMF tones are received.
	EventDTMFReceived EventType = "dtmf.received"
)

DTMF events.

type MultiObserver 

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

MultiObserver fans out events to multiple observers.

func NewMultiObserver 

func NewMultiObserver(observers ...VoiceObserver) *MultiObserver

NewMultiObserver creates a MultiObserver with the given observers.

func (*MultiObserver) Add 

func (m *MultiObserver) Add(observer VoiceObserver)

Add adds an observer.

func (*MultiObserver) OnEvent 

func (m *MultiObserver) OnEvent(ctx context.Context, event VoiceEvent)

OnEvent dispatches the event to all observers.

type NoOpSTTHook 

type NoOpSTTHook struct{}

NoOpSTTHook is an STT hook that does nothing.

func (NoOpSTTHook) AfterTranscribe 

func (NoOpSTTHook) AfterTranscribe(_ context.Context, _ STTCallInfo, _ STTRequest, _ *STTResponse, _ error)

func (NoOpSTTHook) BeforeTranscribe 

func (NoOpSTTHook) BeforeTranscribe(ctx context.Context, _ STTCallInfo, _ STTRequest) context.Context

func (NoOpSTTHook) OnStreamResult 

func (NoOpSTTHook) OnStreamResult(_ context.Context, _ STTCallInfo, _ STTResponse)

func (NoOpSTTHook) WrapStreamWriter 

func (NoOpSTTHook) WrapStreamWriter(_ context.Context, _ STTCallInfo, _ STTRequest, writer io.WriteCloser) io.WriteCloser

type NoOpTTSHook 

type NoOpTTSHook struct{}

NoOpTTSHook is a TTS hook that does nothing.

func (NoOpTTSHook) AfterSynthesize 

func (NoOpTTSHook) AfterSynthesize(_ context.Context, _ TTSCallInfo, _ TTSRequest, _ *TTSResponse, _ error)

func (NoOpTTSHook) BeforeSynthesize 

func (NoOpTTSHook) BeforeSynthesize(ctx context.Context, _ TTSCallInfo, _ TTSRequest) context.Context

func (NoOpTTSHook) WrapStream 

func (NoOpTTSHook) WrapStream(_ context.Context, _ TTSCallInfo, _ TTSRequest, stream <-chan []byte) <-chan []byte

type Observable 

type Observable interface {
	// AddObserver registers an observer to receive events.
	AddObserver(observer VoiceObserver)

	// RemoveObserver unregisters an observer.
	RemoveObserver(observer VoiceObserver)
}

Observable is implemented by types that emit voice events.

type STTCallInfo 

type STTCallInfo struct {
	// CallID is a unique identifier for correlating BeforeRequest/AfterResponse.
	CallID string

	// Provider is the STT provider name (e.g., "deepgram", "openai").
	Provider string

	// StartTime is when the operation started.
	StartTime time.Time

	// Model is the STT model being used.
	Model string

	// Language is the expected language.
	Language string
}

STTCallInfo contains information about an STT operation.

type STTHook 

type STTHook interface {
	// BeforeTranscribe is called before STT transcription.
	// Returns a potentially modified context for propagation.
	BeforeTranscribe(ctx context.Context, info STTCallInfo, req STTRequest) context.Context

	// AfterTranscribe is called after STT transcription completes.
	AfterTranscribe(ctx context.Context, info STTCallInfo, req STTRequest, resp *STTResponse, err error)

	// WrapStreamWriter wraps an STT audio writer for observability.
	// The wrapper should track bytes written.
	WrapStreamWriter(ctx context.Context, info STTCallInfo, req STTRequest, writer io.WriteCloser) io.WriteCloser

	// OnStreamResult is called for each streaming transcription result.
	OnStreamResult(ctx context.Context, info STTCallInfo, resp STTResponse)
}

STTHook provides observability for STT operations.

type STTRequest 

type STTRequest struct {
	// AudioSize is the size of the audio in bytes (for non-streaming).
	AudioSize int64

	// Encoding is the audio encoding (e.g., "pcm", "mulaw", "mp3").
	Encoding string

	// SampleRate is the audio sample rate.
	SampleRate int

	// Channels is the number of audio channels.
	Channels int

	// IsStreaming indicates if this is a streaming transcription.
	IsStreaming bool
}

STTRequest contains the STT request details.

type STTResponse 

type STTResponse struct {
	// Transcript is the transcribed text.
	Transcript string

	// TranscriptLength is the character count.
	TranscriptLength int

	// Confidence is the transcription confidence (0-1).
	Confidence float64

	// AudioDuration is the duration of audio processed.
	AudioDuration time.Duration

	// Latency is the processing latency.
	Latency time.Duration

	// IsFinal indicates if this is a final transcription result.
	IsFinal bool
}

STTResponse contains the STT response details.

type TTSCallInfo 

type TTSCallInfo struct {
	// CallID is a unique identifier for correlating BeforeRequest/AfterResponse.
	CallID string

	// Provider is the TTS provider name (e.g., "elevenlabs", "openai").
	Provider string

	// StartTime is when the operation started.
	StartTime time.Time

	// VoiceID is the voice being used.
	VoiceID string

	// Model is the TTS model being used.
	Model string
}

TTSCallInfo contains information about a TTS operation.

type TTSHook 

type TTSHook interface {
	// BeforeSynthesize is called before TTS synthesis.
	// Returns a potentially modified context for propagation.
	BeforeSynthesize(ctx context.Context, info TTSCallInfo, req TTSRequest) context.Context

	// AfterSynthesize is called after TTS synthesis completes.
	AfterSynthesize(ctx context.Context, info TTSCallInfo, req TTSRequest, resp *TTSResponse, err error)

	// WrapStream wraps a TTS audio stream for observability.
	// The wrapper should track bytes read and call AfterSynthesize on EOF/error.
	WrapStream(ctx context.Context, info TTSCallInfo, req TTSRequest, stream <-chan []byte) <-chan []byte
}

TTSHook provides observability for TTS operations.

type TTSRequest 

type TTSRequest struct {
	// Text is the text to synthesize.
	Text string

	// TextLength is the character count.
	TextLength int

	// OutputFormat is the audio format (e.g., "mp3", "pcm", "ulaw").
	OutputFormat string

	// SampleRate is the audio sample rate.
	SampleRate int
}

TTSRequest contains the TTS request details.

type TTSResponse 

type TTSResponse struct {
	// AudioSize is the size of the generated audio in bytes.
	AudioSize int64

	// Duration is the duration of the generated audio.
	Duration time.Duration

	// Latency is the time from request to first byte (for streaming).
	Latency time.Duration
}

TTSResponse contains the TTS response details.

type VoiceEvent 

type VoiceEvent struct {
	// Type identifies the event type.
	Type EventType

	// Timestamp is when the event occurred.
	Timestamp time.Time

	// CallID is the unique identifier for the call (if applicable).
	CallID string

	// Provider is the name of the provider (e.g., "twilio", "telnyx").
	Provider string

	// Direction is "inbound" or "outbound" for call events.
	Direction string

	// From is the caller ID.
	From string

	// To is the called number.
	To string

	// Duration is the call duration (for ended events).
	Duration time.Duration

	// Error contains error details (for failed/error events).
	Error error

	// Metadata holds additional provider-specific data.
	Metadata map[string]any
}

VoiceEvent represents an observable event in the voice system.

type VoiceObserver 

type VoiceObserver interface {
	// OnEvent is called when a voice event occurs.
	// Implementations must be safe for concurrent use.
	OnEvent(ctx context.Context, event VoiceEvent)
}

VoiceObserver receives voice events for observability. Implementations should be non-blocking and handle errors internally.

type VoiceObserverFunc 

type VoiceObserverFunc func(ctx context.Context, event VoiceEvent)

VoiceObserverFunc is a function adapter for VoiceObserver.

func (VoiceObserverFunc) OnEvent 

func (f VoiceObserverFunc) OnEvent(ctx context.Context, event VoiceEvent)

OnEvent implements VoiceObserver.

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.