Enabling Sentry Performance Tracing: Using tracesSampleRate and tracesSampler

This document provides a comprehensive guide for adding performance monitoring support to the Sentry SDK. It explains how to enable distributed tracing by setting one of the two new SDK configuration options, tracesSampleRate or tracesSampler. If neither option is set, both default to undefined, leaving the SDK to decide whether to sample a transaction. tracesSampleRate must be a float between 0.0 and 1.0. The value represents the probability that any given transaction will be sent to Sentry (e.g., 0.0 means never, 1.0 means always). The same rate applies to all child spans of the transaction. tracesSampler is a callback invoked at the start of a transaction. It receives a samplingContext object containing the transaction context, an optional parentSampled flag, and any custom sampling data. The callback must return a number between 0.0 and 1.0 (or a boolean true / false which maps to 1.0 / 0.0) to determine the sampling rate for that specific transaction. Returning 0.0 forces the transaction to be dropped, while 1.0 forces it to be sent.

The SDK also enforces a maxSpans limit (default 1000) to prevent unbounded memory usage and OOM errors. When the limit is reached, additional spans are discarded.

Transactions are a special kind of Span with a name field and a type: "transaction". Unlike regular spans, a transaction can be sent as an event and is wrapped in an Envelope before transmission. The document details the differences between Transaction and Span, including how finish() works for each.

Sampling decisions follow a priority order: an explicit sampled flag passed to startTransaction overrides everything; otherwise, tracesSampler is consulted; if absent, the parent transaction’s decision is inherited; finally, tracesSampleRate is used.

The sentry-trace header carries the trace ID, span ID, and optional sampled flag (e.g., sentry-trace = traceid-spanid-sampled). This header is used for trace propagation across HTTP requests. The document also describes how the trace context JSON object (including trace_id, public_key, release, environment, user, and transaction) is embedded in the envelope header and how it is encoded into the tracestate header using base64 without padding.

Implementation guidelines require the SDK to create a new trace context from the current scope, attach the trace context to envelope headers for transaction events, and propagate tracestate headers on outgoing HTTP requests. Incoming tracestate headers must be parsed and the trace context frozen (state SENT ) so it cannot be altered later.

The guide also outlines client options for enabling trace sampling, naming conventions for those options, and the process for adding envelope headers. It stresses that once a trace context is sent, it becomes immutable, and any later changes to release, environment, or user data must not affect the already‑sent context.

Finally, the document provides a taxonomy of span operations across different domains (Browser, Web Server, Database, Serverless, Mobile, Messaging, etc.) following OpenTelemetry semantic conventions. Each category includes example usages such as http.client, db.sql.query, ui.react.render, and faas.aws.lambda, allowing SDK developers to tag spans consistently.