Examples
Runnable examples, instrumentation guides, recipes, and migration paths.
Use this page to pick the right starting point. Runnable examples are things you can clone, scaffold, or run locally. Reference examples are docs and snippets to copy into an existing app.
Fastest paths
| Goal | Start here | Type |
|---|---|---|
| First run from a fresh checkout | Getting started | Guide |
| Run the prebuilt image without cloning | ghcr.io/dev-sawan-ruparel/obs-unified | Prebuilt image |
| Run everything from one local image with sample data | Dockerfile.local via pnpm local:image && pnpm local:run | Runnable image |
| Try obs-unified with realistic traffic | demo/ | Runnable demo |
| Run the end-to-end AutoSRE Scenario D testbed | pnpm e2e:autosre | Runnable verification suite |
Scaffold a new React + Hono app (interactive, or non-interactive with --yes) | pnpm dlx @obsunified/cli create my-app --template react-vite --yes | Runnable template |
| Add obs-unified to an existing React + Hono app | React + Hono walkthrough | Walkthrough |
| Add obs-unified to an existing Python Flask app | Python Flask walkthrough | Walkthrough |
| Add browser analytics only | Analytics SDK | Reference |
| Add TypeScript backend telemetry | Telemetry SDK | Reference |
| Instrument Python, JVM, or .NET | Language recipes | Recipes |
Runnable examples
| Example | What it shows | Run / entry point |
|---|---|---|
ghcr.io/dev-sawan-ruparel/obs-unified | Prebuilt all-in-one release image: Node collector, dashboard, embedded Postgres, file blob storage. Fails closed without INGEST_KEY and DASHBOARD_PASSWORD. | docker run per Installation |
Dockerfile.local | All-in-one local image with Postgres, collector, dashboard, file blob storage, and seed data. | pnpm local:image && pnpm local:run |
packages/cli/templates/react-vite/ | React + Vite frontend, Hono Node API, AnalyticsProvider, backend spans, and click-to-trace propagation. | pnpm dlx @obsunified/cli create my-app --template react-vite --yes |
packages/cli/templates/vanilla-ts/ | Browser-only Vite + TypeScript analytics. | pnpm dlx @obsunified/cli create my-app --template vanilla-ts --yes |
packages/cli/templates/hono-workers/ | Hono on Cloudflare Workers with backend telemetry wiring. | pnpm dlx @obsunified/cli create my-api --template hono-workers --yes |
apps/obs-demo/ | AI calls, RAG, tool calls, session tracking, and evaluation scenarios. | pnpm dev, then curl http://127.0.0.1:8787/api/demo/run-all |
scripts/e2e-autosre/ (run-all.sh) | End-to-end AutoSRE Scenario D testbed: deploy change event, traffic-normalized cohort lift (v2.4.1 vs v2.4.0), noisy-neighbor contention check, counterfactual eval verification, and remediation grant claim. | pnpm e2e:autosre |
apps/collector-node/ | Standalone Node collector with Postgres + RustFS (S3-compatible). | docker compose up -d from apps/collector-node |
demo/ | OpenTelemetry Astronomy Shop feeding obs-unified with polyglot microservice traffic. | pnpm demo:setup, pnpm demo:preflight, pnpm demo:up |
SDK examples
| Runtime | Example | Notes |
|---|---|---|
| Node.js / TypeScript | sdks/node/examples/basic.ts | First-party Node SDK usage |
| Node.js / TypeScript | sdks/node/examples/smoke.mjs | Lightweight SDK smoke path |
| Go | sdks/go/examples/basic/main.go | Go SDK init and span conventions |
| Rust | sdks/rust/examples/basic.rs | Rust SDK init and helper usage |
Instrumentation guides
| App shape | Guide |
|---|---|
| React + Hono | Instrumenting your app |
| Python + Flask | Python Flask instrumentation |
| Browser / React analytics | Analytics SDK |
| TypeScript backend / Workers | Telemetry SDK |
| Deeper backend instrumentation | SDK API reference |
| Profiling / pprof | docs/howto/profiling.md in the repo |
| eBPF / host metrics | docs/howto/ebpf.md in the repo |
Language recipes
| Runtime | Recipe |
|---|---|
| Python | docs/recipes/python.md |
| JVM / Java / Kotlin | docs/recipes/jvm.md |
| .NET | docs/recipes/dotnet.md |
| Go | sdks/go/README.md |
| Rust | sdks/rust/README.md |
| SDK skeleton for contributors | sdks/_template/README.md |
Migration examples
| Source | Guide |
|---|---|
| Sentry | docs/migrate/from-sentry.md |
| PostHog | docs/migrate/from-posthog.md |
| Honeycomb | docs/migrate/from-honeycomb.md |
Old @obs/* package scope | docs/migrate/from-obs-scope.md |
Verification
After wiring any example, verify the collector and browser CORS path:
pnpm dlx @obsunified/cli doctor http://localhost:8790 --origin http://localhost:5173For browser examples, the origin should match the app you are testing. For the Astronomy Shop demo, use http://localhost:8080.
Installation
Pull the prebuilt image from GHCR, build the all-in-one local image with sample data, or install the editable local repo.
SDKs and MCP
First-party SDKs for TypeScript, Go, and Rust, a browser SDK for usage and replay, and an MCP server for agent investigations. They share one identity-propagation contract.