Welcome

obs-unified is unified observability for every signal, built for agentic debugging. Traces, logs, AI calls, agent actions, usage events, replays, alerts, profiles, and analyses flow into one collector, share one identity chain, and appear in one telemetry graph agents can traverse from user action to backend trace, logs, replay, AI cost, MCP tool context, and CPU profile.

Self-hosting is the deployment model, not the whole pitch: the default hosted path runs on Cloudflare Workers with D1 and R2, while the Node collector path uses Postgres and S3-compatible blob storage.

What's in this documentation

• Getting started — choose Docker or local dev, then choose seeded data, Astronomy Shop, or your own app.
• Installation — the shortest current install path for the all-in-one local image and the editable local repo.
• Examples — runnable demos, scaffold templates, SDK examples, recipes, and migration guides.
• SDKs — @obsunified/analytics-sdk (browser, click + interaction propagation), @obsunified/telemetry-sdk (Node/Workers), plus Go and Rust.
• SDK API reference — compact method map for init, interaction stamping, LLM/tool spans, MCP context propagation, and Cloudflare wrappers.
• Evidence reference — machine-readable evidence references with entity IDs, routes, confidence, citations, and pivots.
• Evidence retrieval (CCR) — compact, token-budgeted evidence bundles and retrieval refs that let agents pull just the debugging signal, not the raw firehose.
• Agent Action Graph — debug agent runs as causal workflows across LLM calls, retrievals, tool calls, traces, logs, profiles, and eval cases.
• MCP server — expose read-only investigation tools to AI agents without granting ingest credentials.
• Instrumenting — concrete React + Worker examples that produce signals correlated end-to-end.
• Python Flask instrumentation — OpenTelemetry setup for a Flask service.
• What to expect — the click-to-CPU scenarios the platform was built around, with the rail's role at every hop.
• Production operations — reverse proxy, Postgres tuning, storage retention, and Kubernetes notes.
• Vendor comparison — side-by-side feature comparison with Datadog, Sentry, and PostHog.

The unified-stack promise

That identity skeleton is the unifying layer. The SDKs propagate it, the collector stores it, and the dashboard plus MCP server use it to connect product behavior, backend execution, agent actions, AI cost, logs, replay, alerts, profiles, and analyses. Read the SDKs page for which ID is minted where, Agent Action Graph for agent causality, and What to expect for the journeys it makes possible.

The click-to-CPU path is deliberately precise: the browser mints interaction_id, the backend stamps it onto spans/logs/AI calls/MCP tool context, and profiles join through the trace_id those spans belong to. In shorthand: