Quickstart 1: Tiny Shop

You build a two-folder shop: an Express API and a React page. First they work with no telemetry at all. Then you start the ouo11y stack from one file, trace the API with the OpenTelemetry Node SDK, add @ouo11y/browser to the page, and break things on purpose. At the end, one click in the browser is one trace from the button to the API’s own spans, and Grafana shows a crashed session with that trace and a replay of what you clicked.

Time: about 30 minutes. You need: Node 24 or newer, Docker Desktop, VS Code, and pull access to the ouo11y images (see below).

What you build

frontend/ :5173

Tiny Shop pageReact · @ouo11y/browser
sessions, errors, replay

fetch + traceparent

backend/ :5001

Tiny Shop APIExpress · OpenTelemetry Node SDK
auto + manual spans

OTLP

stack/ (one compose file)

Collector:4318 OTLP · :4319 replay

Loki · Tempo · Mimirevents · traces · metrics

rum-apisessions · replay store

You

Grafana :3000Explore · ouo11y RUM app

Two apps on your laptop send OTLP to the collector of a local ouo11y stack; Grafana shows the session.

The page sends its own telemetry to the collector too (spans, events and replay chunks); the arrow above shows the call that ties the two apps together. Here is what happens when you click Checkout at the end of the quickstart. Press Play to step through it.

Browser

API

Collector

Grafana

1. 1 click Checkout · fetch span starts
2. 2 OPTIONS /api/checkout · CORS preflight for traceparent, baggage
3. 3 POST /api/checkout · traceparent + baggage(session.id)
4. 4 manual spans · checkout, validate cart, charge card
5. 5 200 { orderId }
6. 6 server spans · OTLP /v1/traces
7. 7 fetch span, cart.added, replay · :4318 and :4319
8. 8 one trace, one session · Tempo, Loki, ouo11y RUM

▶ PlayShow all

The browser's fetch span becomes the root of the API's trace, and session.id rides along in baggage.

The steps

Each page ends with what you should see before you go on.

1. The plain appAn Express API and a React page, working, with no telemetry.

2. The stackGrafana, Loki, Tempo, Mimir, rum-api and the collector from one compose file.

3. Backend tracesThe OpenTelemetry Node SDK, manual spans, and the API's traces in Tempo.

4. The browser SDK@ouo11y/browser in the React app, with trace headers to the API.

5. See it in GrafanaOne trace across both apps, the browser events, and the crashed session.

6. Clean up and troubleshootingStop the stack, and what to do when something does not work.

Early access: the images are private

The ouo11y container images on ghcr.io are private while we are in early access, so step 2 only works with pull access. Email hello@ouo11y.com for it; we answer quickly. Step 1 needs no access, and everything else (the SDKs, the files on these pages) is public.

The finished files

Every file is on these pages, ready to copy. If you get stuck, compare with the finished backend/ and frontend/ folders, the ones you have at the end:

⬇ Download the finished files (tiny-shop.zip)

Short on time? Run the finished files

1. Download and unzip the finished files above. You get a tiny-shop/ folder with backend/ and frontend/.

2. Start the stack as on page 2.

3. In tiny-shop/backend:

   npm install

   npm start

   It prints [otel] tracing to http://localhost:4318/v1/traces and serves on :5001.

4. In tiny-shop/frontend, in a second terminal:

   npm install

   npm run dev

5. Open http://localhost:5173, click Add, Checkout, Call broken API and Throw error, then go to page 5.

What you should see at the end

In Grafana, under More apps → ouo11y RUM → Sessions, one session with the status crashed. It has the trace of your checkout, from the browser’s POST span down to charge card in the API, and a replay of your clicks.