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

> Learn how tracesSampleRate controls event transmission in web tracing SDKs. Adjust this value from 0 to 1 to reduce overhead and optimize performance monitoring.

- Repository: [m-cheng-web/web-tracing](https://github.com/m-cheng-web/web-tracing)
- Tags: performance
- Published: 2026-03-06

---

**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`](https://github.com/m-cheng-web/web-tracing/blob/main/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.

```typescript
// 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.

```typescript
// 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`](https://github.com/m-cheng-web/web-tracing/blob/main/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:

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

```

Here, `randomBoolean(rate)`—implemented in [`utils/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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.