Instrumenting an app

Most teams do not fail at observability because they picked the wrong vendor. They fail because nobody decided what a line of application code is allowed to emit. One engineer dumps the cart with console.log. Another wraps the payment call in a span. A third fires track('Error') from a catch block. Six months later the dashboard is loud and the questions you actually have — who dropped out of checkout, which query stalled, which release broke it — still take three tools and a guess.

This course is the decision layer. The other Learn guides explain each signal. These eight chapters tell you when to use which one, where the call lives in the app, and what a finished system looks like when the signals share an identity.

Snippets use one example so the figures compose: a browser storefront and an API that charges a card. The product page is /products/trail-runner, SKU TR-900. TypeScript and PHP appear because that pairing puts two official SDKs on one trace. The same calls exist in Dart, Flutter, Node, and the other official SDKs. Swap the SKU for your core action — signup, upgrade, publish.

Four signals, four questions

Talaria answers four questions from official SDKs:

• What broke? — An event (exception or rare structured message) is fingerprinted into an issue. See errors, traces, and replay.
• How long did the work take? — A transaction is a sampled root span; child spans are the waterfall. See SDK-native APM.
• What were people trying to do? — Named analytics events, visitors, sessions, funnels. See product analytics.
• What did the session look like? — A retained browser replay, metered separately, joined by replayId.

Those are different envelopes. Errors, spans, analytics, and replay each have their own ingest path. Stuffing a span field onto an error event, or an exception into track, is how the join breaks.

The example: a checkout

The journey we will instrument is the one you already see in the analytics figures:

1. $pageview on the landing page and the product page.
2. product_viewed when the product page is meaningful, not on every hover.
3. add_to_cart with sku, price, size.
4. checkout_started when they commit to paying.
5. order_completed or checkout_failed when the charge returns.

Alongside that: a pageload transaction in the browser, a POST /checkout transaction on the API, child spans for Stripe and MySQL, breadcrumbs before the throw, and a replay that starts when an error fires.

The join keys

You do not invent a correlation scheme. Official SDKs attach what they already know:

• traceId / spanId — the in-flight trace, including W3C traceparent from the browser fetch into the API.
• replayId — the current recording, when the browser SDK is retaining one.
• userId, anonymousId, sessionId — who, which browser, which visit.
• release — the version or SHA the SDK sends — and environment — the value bound to the API key, stamped by the server.

That is why you install one SDK per process and turn signals on, rather than wiring a second analytics tool that will never hold your stack traces. The dashboard then gives you Issues, Performance, Analytics, and Replays in one place.

How to use this course

Eight chapters, in order the first time:

1. This map — what the four signals are, and what the example checkout is.
2. Which call to make — a table of real call sites. Read this before you write a single captureMessage.
3. Errors in application code — exceptions, breadcrumbs, tags, and why info events cost real money.
4. Tracing in application code — where transactions and spans belong, and how sampling works.
5. Analytics in application code — the checkout taxonomy, identify, and server-side track.
6. A checkout, end to end — the same purchase, scene by scene, in TypeScript and PHP.
7. One incident — Monday morning, from a funnel drop to a four-second query.
8. The operating model — the checklist a team can run every week.

After the first pass, treat chapter 2 as the index and chapter 6 as the worked example. The concept guides remain the glossary: open them when you need the definition of a span kind or a funnel window, not when you need to know what to type in CheckoutForm.tsx.

Where the install lives

This course is the decision layer, so it assumes the SDK is already running. For installation, start at Quickstart and your SDK, then come back here to decide what each line of application code should emit.

What “done” looks like

A checkout is instrumented when all of the following are true:

• A thrown payment error is one issue, with View trace and View replay when those IDs exist.
• Performance shows POST /checkout as a named transaction, with Stripe and MySQL as children — not a raw URL with a UUID in the path.
• Analytics Overview can count order_completed, and a saved funnel from $pageview to that event has drop-off you can click into.
• The person who dropped is a visitor or a userId, not an anonymous blob you cannot replay.
• Sampling is deliberate: errors always traced, successful transactions at a rate you can explain to finance.