Observability Options

ObservabilityOptions is a single, declarative way to enable observability features — recording, traces, metrics, and logs — directly when you start an AgentSession. Instead of toggling each feature in different places, you pass one config object to session.start() and the framework wires everything up.

Quick Start

main.py

from videosdk.agents import (
    AgentSession,
    ObservabilityOptions,
    RecordingOptions,
    TracesOptions,
    MetricsOptions,
    LoggingOptions,
)

session = AgentSession(agent=agent, pipeline=pipeline)

await session.start(
    wait_for_participant=True,
    run_until_shutdown=True,
    observability=ObservabilityOptions(
        recording=RecordingOptions(video=True),
        traces=TracesOptions(
            enabled=True,
            export_url="https://otlp.example.com/v1/traces",
        ),
        metrics=MetricsOptions(
            enabled=True,
            export_url="https://otlp.example.com/v1/metrics",
        ),
        logs=LoggingOptions(enabled=True, level="DEBUG"),
    ),
)

tip

Each field is optional. Pass only the features you want to enable — omitted fields stay off.

ObservabilityOptions Parameters

Parameter	Type	Default	Description
recording	Optional[RecordingOptions]	None	Configure session recording (audio, video, screen share)
traces	Optional[TracesOptions]	None	Configure OpenTelemetry trace collection and OTLP export
metrics	Optional[MetricsOptions]	None	Configure OpenTelemetry metric collection and OTLP export
logs	Optional[LoggingOptions]	None	Configure log level filtering and optional log export

note

TracesOptions, MetricsOptions, LoggingOptions, and RecordingOptions are the same classes used in RoomOptions. ObservabilityOptions simply lets you pass them at session.start() instead of at room construction — pick whichever entry point suits your code structure.

---

Recording

Provide a RecordingOptions to capture the session. Audio is recorded by default; pass additional flags to also record video and/or screen share.

RecordingOptions

Parameter	Type	Default	Description
video	bool	False	Record the agent's camera video track (composite audio+video participant recording)
screen_share	bool	False	Record the screen-share track. Requires vision=True in RoomOptions

main.py

from videosdk.agents import ObservabilityOptions, RecordingOptions

await session.start(
    observability=ObservabilityOptions(
        recording=RecordingOptions(video=True),
    ),
)

note

For full details on recording behavior, output formats, and the difference between participant, track, and meeting recording, see the Recording doc.

---

Traces

Stream OpenTelemetry traces (spans for STT, LLM, TTS, EOU, tool calls, etc.) to your own observability backend over OTLP/HTTP — for example Grafana Tempo, Honeycomb, Jaeger, Datadog, or any OTLP-compatible collector.

TracesOptions

Parameter	Type	Default	Description
enabled	bool	True	Enable trace collection
export_url	Optional[str]	None	OTLP/HTTP endpoint that should receive trace spans
export_headers	Optional[Dict[str, str]]	None	Custom headers for the export endpoint (e.g., auth tokens)

main.py

from videosdk.agents import ObservabilityOptions, TracesOptions

await session.start(
    observability=ObservabilityOptions(
        traces=TracesOptions(
            enabled=True,
            export_url="https://otlp.example.com/v1/traces",
            export_headers={"Authorization": "Bearer your-token"},
        ),
    ),
)

tip

Traces are also available on the VideoSDK Dashboard without any extra setup. Use TracesOptions when you want to ship traces to an external system in addition to (or instead of) the dashboard.

---

Metrics

Export pipeline metrics (latency, durations, token usage) to your own OTLP-compatible metrics backend — for example Prometheus (via OTLP), Grafana Mimir, Datadog, or New Relic.

MetricsOptions

Parameter	Type	Default	Description
enabled	bool	True	Enable metrics collection
export_url	Optional[str]	None	OTLP/HTTP endpoint that should receive metric points
export_headers	Optional[Dict[str, str]]	None	Custom headers for the export endpoint (e.g., auth tokens)

main.py

from videosdk.agents import ObservabilityOptions, MetricsOptions

await session.start(
    observability=ObservabilityOptions(
        metrics=MetricsOptions(
            enabled=True,
            export_url="https://otlp.example.com/v1/metrics",
            export_headers={"Authorization": "Bearer your-token"},
        ),
    ),
)

tip

For programmatic, in-process access to the same metrics, use Pipeline Observability hooks (@pipeline.metrics.on(...)).

---

Logs

Filter the session's log output by level, and optionally export logs to an external collector. Useful for cranking up verbosity in development or shipping structured logs to your SIEM in production.

LoggingOptions

Parameter	Type	Default	Description
enabled	bool	False	Enable log export to the configured export_url
level	str	"INFO"	Log level filter — one of "DEBUG", "INFO", "WARNING", "ERROR"
export_url	Optional[str]	None	OTLP/HTTP endpoint that should receive log records
export_headers	Optional[Dict[str, str]]	None	Custom headers for the export endpoint (e.g., auth tokens)

main.py

from videosdk.agents import ObservabilityOptions, LoggingOptions

# Local: just bump the log level for the session
await session.start(
    observability=ObservabilityOptions(
        logs=LoggingOptions(level="DEBUG"),
    ),
)

# Remote: also ship logs to an OTLP collector
await session.start(
    observability=ObservabilityOptions(
        logs=LoggingOptions(
            enabled=True,
            level="INFO",
            export_url="https://otlp.example.com/v1/logs",
            export_headers={"Authorization": "Bearer your-token"},
        ),
    ),
)

---

Complete Example

For a runnable script that turns on recording, traces, metrics, and logs together inside session.start(), see the Observability Hooks example on GitHub.

Related

Observability Hooks Example

Full runnable example with ObservabilityOptions, metrics, recording, and error hooks

Pipeline Observability

Hooks for metrics, errors, recording lifecycle, and context access

Session Analytics

Inspect sessions, transcripts, and latency on the VideoSDK Dashboard

Trace Insights

Granular per-turn breakdown of STT, LLM, TTS, and tool calls

Recording

Recording types, options, and lifecycle