What Is the `tracesSampleRate` Option and How Does It Affect Performance Monitoring?

The tracesSampleRate option controls the percentage of events that the web-tracing SDK actually transmits to your server, defaulting to 1 (100%) but accepting any value between 0 and 1 to reduce overhead.

The tracesSampleRate configuration is a global sampling mechanism defined in the SDK’s initialization options. It determines whether generated events—including page views, performance metrics, errors, and custom tracking data—are uploaded or discarded locally. By adjusting this single value, developers can balance comprehensive observability against network bandwidth and client-side resource consumption.

Understanding the tracesSampleRate Configuration

Option Definition and Default Value

In packages/core/src/lib/options.ts, the SDK declares tracesSampleRate as a numeric property with a default value of 1. This means that, out of the box, every captured event is queued for transmission.

// packages/core/src/lib/options.ts#L40-L42
tracesSampleRate: 1, // 采样率

The default behavior provides full-resolution monitoring suitable for low-traffic applications or debugging scenarios. For high-volume production environments, lowering this value becomes essential to prevent overwhelming your ingestion pipeline.

Validation Constraints

The SDK enforces strict validation to ensure data integrity. As defined in the same file, the type system guarantees that tracesSampleRate must be a number between 0 and 1 inclusive.

// packages/core/src/lib/options.ts#L8-L10
tracesSampleRate?: number; // 0-1

Setting the value to 0 effectively pauses automatic transmission (unless manually flushed), while 1 ensures complete coverage. Any fractional value, such as 0.2, instructs the SDK to upload approximately 20% of events using probabilistic sampling.

How tracesSampleRate Works Under the Hood

The Sampling Guard in SendData.emit

The actual filtering logic resides in packages/core/src/lib/sendData.ts inside the emit method. Before an event enters the transmission queue, the SDK evaluates it against the configured rate:

// packages/core/src/lib/sendData.ts#L39-L44
if (!flush && !randomBoolean(options.value.tracesSampleRate)) return;

Here, randomBoolean(rate)—implemented in utils/index.ts—returns true with probability equal to the tracesSampleRate. If the check fails, the function returns early, preventing the event from consuming serialization CPU, memory, or network resources. This early-exit pattern is critical for performance on low-end devices.

Force-Send Override with Flush

Despite the global sampling rate, specific events can bypass the probabilistic filter. When calling sendData.emit with the flush parameter set to true, the SDK skips the randomBoolean check entirely:

sendData.emit(eventData, true); // flush = true forces immediate upload

This override is utilized by manual flush operations and sendData.sendLocal, ensuring that critical diagnostics or end-of-session reports reach your server regardless of the global tracesSampleRate setting.

Interaction with Event Hooks

Fine-grained control remains available through the beforePushEventList hook, which executes after the global sampling step. This architecture allows you to maintain a low tracesSampleRate for general load reduction while using custom logic in beforePushEventList to guarantee specific high-priority events are never dropped.

Performance Impact and Trade-offs

Adjusting the tracesSampleRate creates a direct trade-off between data granularity and application performance:

• Reduced Network Traffic – Lower sample rates decrease the number of HTTP payloads, cutting bandwidth consumption and server ingestion costs proportionally.
• Lower CPU and Memory Overhead – Events that fail the sampling check are discarded before serialization and queue management, freeing up processing cycles on the client.
• Diminished Statistical Significance – Extremely low values (e.g., 0.01) may miss rare performance anomalies or infrequent errors, making it harder to diagnose edge-case issues.

For high-traffic single-page applications, a tracesSampleRate of 0.1 to 0.2 often provides sufficient statistical insight while eliminating 80-90% of monitoring overhead.

Implementing tracesSampleRate in Your Application

Configure the sampling rate during SDK initialization to match your observability requirements:

import { initOptions } from '@web-tracing/core';

// Full fidelity monitoring (default behavior)
initOptions({
  dsn: 'https://example.com/collect',
  appName: 'MyApp',
  tracesSampleRate: 1
});

// Production-savvy 20% sampling
initOptions({
  dsn: 'https://example.com/collect',
  appName: 'MyApp',
  tracesSampleRate: 0.2
});

To force-send a specific event regardless of the global configuration:

import { sendData } from '@web-tracing/core';

// This event uploads immediately, bypassing the 20% sample rate
sendData.emit(
  { type: 'performance', data: { duration: 120 } },
  true // flush parameter
);

User-facing documentation in docs/guide/use/options.md confirms these behaviors and provides additional context for configuration decisions.

Summary

• tracesSampleRate is defined in packages/core/src/lib/options.ts with a default value of 1, meaning 100% of events transmit by default.
• The sampling logic lives in packages/core/src/lib/sendData.ts, where randomBoolean probabilistically filters events before serialization.
• Values must be between 0 and 1; 0 blocks automatic transmission while 1 allows all events.
• Passing flush = true to emit() overrides the sampling rate for critical events that must reach the server.
• Lowering the rate reduces network, CPU, and memory overhead but decreases the resolution of your performance data.

Frequently Asked Questions

What happens if I set tracesSampleRate to 0?

Setting tracesSampleRate to 0 prevents the SDK from automatically uploading any events. The randomBoolean check will always return false in packages/core/src/lib/sendData.ts, causing immediate return from the emit method. However, you can still transmit data manually by calling sendData.emit with the flush parameter set to true or by invoking specific flush methods that bypass the sampling guard.

How does tracesSampleRate differ from beforePushEventList filtering?

tracesSampleRate operates as a global probabilistic gate that runs before event serialization and before the beforePushEventList hook executes. The hook allows you to filter or mutate specific event types after the sampling decision. This two-stage architecture lets you use a low global sample rate for general traffic reduction while using beforePushEventList to ensure 100% capture of specific critical events.

Can I change tracesSampleRate after initialization?

According to the source code in packages/core/src/lib/options.ts, tracesSampleRate is part of the initialization options object. While the documentation does not explicitly expose a runtime setter, the options are typically reactive in modern SDKs. For dynamic sampling adjustments, you should consult the specific version implementation or re-initialize the SDK, as the sampling check in sendData.ts reads from options.value.tracesSampleRate at emit-time.

What is the performance cost of tracesSampleRate: 1 on mobile devices?

With tracesSampleRate: 1, every event undergoes serialization, queue management, and network transmission. On constrained mobile devices or pages generating high event volumes, this creates measurable CPU and memory pressure. The source code mitigates this via early exit in SendData.emit, but full sampling still incurs the overhead of object construction and the randomBoolean check itself. For mobile-optimized applications, the documentation recommends reducing this value to 0.1 or lower.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}