Skip to main content
The observability module provides a hidden-by-default browser dashboard that exposes real-time and historical insight into your agent’s behavior. Enable it with a single flag and open /obs/ in your browser.

​
Quick Start

from definable.agent import Agent

agent = Agent(
  model="openai/gpt-4o-mini",
  observability=True,  # enables the dashboard
)

agent.serve(enable_server=True)
# Open http://localhost:8000/obs/
That’s it. The dashboard mounts on the same server as your agent API — no extra ports, no extra processes.

​
What You Get

The dashboard provides seven views accessible from the sidebar:
ViewWhat it shows
OverviewTotal runs, success rate, token usage, cost, run cadence chart
Live EventsReal-time event stream from the agent pipeline (SSE)
SessionsHistorical trace sessions from JSONL files
Run DetailPhase timeline, tool calls, input/output for a single run
CompareSide-by-side diff of two runs (tokens, cost, content, tools)
ToolsPer-tool call counts, error rates, average latency
ModelsPer-model token usage, cost breakdown

​
Configuration

Use ObservabilityConfig for fine-grained control: 
from definable.agent import Agent
from definable.agent.observability import ObservabilityConfig

agent = Agent(
  model="openai/gpt-4o-mini",
  observability=ObservabilityConfig(
    enabled=True,
    trace_dir="./my-traces",   # where JSONL trace files live
    buffer_size=5000,          # live event ring buffer size
    theme="light",             # "dark" (default) or "light"
  ),
)

​
Options

ParameterTypeDefaultDescription
enabledboolFalseWhether the dashboard is active
trace_dirstr"./traces"Directory for JSONL trace files
buffer_sizeint10000Maximum events in the live ring buffer
themestr"dark"Default dashboard theme

​
Composing with Tracing

Observability composes with the existing Tracing system. The ObservabilityExporter is automatically added to your exporter chain: 
from definable.agent import Agent
from definable.agent.tracing.base import Tracing
from definable.agent.tracing.jsonl import JSONLExporter

agent = Agent(
  model="openai/gpt-4o-mini",
  tracing=Tracing(exporters=[JSONLExporter(trace_dir="./traces")]),
  observability=True,
)
# Both JSONLExporter and ObservabilityExporter receive events
This also works with debug=True — all three exporters coexist.

​
API Endpoints

When enabled, these endpoints are available under /obs/api/:
EndpointMethodDescription
/obs/api/healthGETHealth check with buffer/client stats
/obs/api/eventsGETSSE stream of live events
/obs/api/sessionsGETList historical trace sessions
/obs/api/sessions/{id}GETList runs within a session
/obs/api/runs/{id}GETFull replay data for a run
/obs/api/compare?a=...&b=...GETSide-by-side run comparison
/obs/api/metricsGETAggregated metrics snapshot
/obs/api/metrics/timelineGETTime-series buckets
/obs/api/events/export/{id}GETDownload session as JSONL
The dashboard UI at /obs/ consumes these endpoints — you can also use them directly for custom integrations.

​
Themes

The dashboard ships with two themes:
  • Dark (default): Black background with orange accents — terminal aesthetic
  • Light: White background with dark accents
Toggle between them using the sun/moon button in the dashboard header, or set the default via config: 
ObservabilityConfig(enabled=True, theme="light")
Theme preference is saved in localStorage and persists across sessions.

​
FAQ

Don’t pass observability=True (or pass observability=False). The dashboard routes are never mounted and no exporter is created. Zero overhead when disabled.
Use the /obs/api/events/export/{session_id} endpoint to download a session as a JSONL file. You can also access the JSONL files directly in your trace_dir.
Minimal. The ObservabilityExporter appends to a ring buffer and fans out to SSE clients via non-blocking queue puts. Event serialization happens in the existing tracing pipeline. The dashboard is served as static HTML with no server-side rendering.
The dashboard requires agent.serve(enable_server=True) because it mounts on the FastAPI app. For programmatic access to metrics and events, you can use the ObservabilityExporter directly in your code.