How Sentry Implements Distributed Tracing to Connect Frontend and Backend

What Is Tracing?

Tracing records the sequence of events that occur across multiple services during a request, unlike profiling which measures resource usage. A trace is a collection of transactions, each of which is a tree of spans. The root span represents the overall operation, and child spans represent sub‑operations within the same service.

Why Trace?

Modern web applications consist of interconnected components—frontend SPA, backend REST API, task queues, databases, and cron jobs. Each component can be instrumented with the Sentry SDK to emit error data, but without tracing the pieces remain isolated. Tracing links these pieces, allowing you to see how a frontend request propagates to backend services and where latency or failures originate.

Key Concepts

Trace : Identified by a shared trace_id, it groups related transactions.

Transaction : Represents a single logical operation (e.g., a page load or API call) and contains a tree of spans. It also carries a transaction_name such as /store/checkout/ or cron job.

Span : The atomic unit of work inside a transaction. Important fields include parent_span_id, op, description, timestamps, status, tags, and data.

Example: Investigating a Slow Page Load

Assume a web app loads slowly. The page load triggers multiple backend requests, database queries, and external API calls. The article breaks down the flow into:

1 browser transaction (page load)

5 backend transactions (one per request)

1 database transaction (single DB request)

Each transaction is further divided into spans, e.g., the browser transaction contains 7 spans: two JSON request spans, one root span for the whole page load, and three resource request spans (HTML, CSS, JS). The backend transactions contain spans for the request itself, database queries, and API processing. By inspecting the span hierarchy, the article shows that an authentication query in the database consumes more than half of the total latency, pinpointing the bottleneck.

Additional Scenarios

Other examples illustrate measuring user actions in e‑commerce (from "Submit Order" to confirmation), monitoring background cron jobs, and handling asynchronous tasks where child transactions may outlive their parent spans.

Trace Data Model

A trace is not a concrete entity; it is defined by the shared trace_id. Transactions share most attributes with their root span (start/end time, tags). Spans store detailed metadata such as op (operation type) and description (e.g., sql.query with the actual SQL statement). Optional fields like status, tags, and data add context (e.g., function names, HTTP request details).

Special Cases

Trace Duration : Determined by the earliest transaction start and the latest transaction end; a trace itself has no explicit timestamps.

Async Transactions : Child transactions may finish long after the parent transaction, and the order of transaction arrival at Sentry does not guarantee chronological order.

Orphan Transactions : Appear when a service fails to report its transaction, leaving gaps in the trace hierarchy.

Nested Spans : Unlimited depth, but payload size limits impose practical constraints.

Zero‑Duration Spans : Spans whose start and end timestamps are identical, used as markers or when the operation is too fast to measure.

Clock Skew : Inconsistent timestamps across machines can distort ordering; using NTP or cloud‑provider time sync mitigates this.

Sending Data

Spans are not sent individually; the entire transaction is transmitted once the transaction closes. Even if a transaction contains only a root span, it is still sent to Sentry.

Data Sampling

Sampling reduces the volume of collected transactions. For example, a 25% sampling rate on an endpoint receiving 1,000 requests per minute results in roughly 250 transactions being sent. Sampling balances performance impact with the need for sufficient data to draw conclusions.

Consistency in Tracing

Sentry uses a head‑based sampling approach: the originating service decides whether to sample and propagates that decision via request headers to all downstream services. This ensures that either all related transactions are collected or none are, preventing incomplete traces.

“Show me your flowchart while hiding your tables, and I’ll be mystified. Show me your tables, and I won’t need your flowchart because they’re obvious.” — Fred Brooks, The Mythical Man‑Month