Skip to content

feat: add adaptive sampling to node sdk #155

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jy-tan wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: add adaptive sampling to node sdk #155

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 10 additions & 5 deletions docs/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,24 +110,29 @@ Your Tusk Drift API key, required when using Tusk Cloud for storing and managing

This will securely store your auth key for future replay sessions.

## TUSK_SAMPLING_RATE
## TUSK_RECORDING_SAMPLING_RATE

Controls what percentage of requests are recorded during trace collection.

- **Type:** Number between 0.0 and 1.0
- **Default:** 1.0 (100% of requests)
- **Precedence:** This environment variable is overridden by the `samplingRate` parameter in `TuskDrift.initialize()`, but takes precedence over the `sampling_rate` setting in `.tusk/config.yaml`
- **If unset:** Falls back to `.tusk/config.yaml` and then the default base rate of `1.0`
- **Precedence:** This environment variable is overridden by the `samplingRate` parameter in `TuskDrift.initialize()`, but takes precedence over `recording.sampling.base_rate` and the legacy `recording.sampling_rate` setting in `.tusk/config.yaml`
- **Scope:** This only overrides the base rate. It does not change `recording.sampling.mode` or `recording.sampling.min_rate`

**Examples:**

```bash
# Record all requests (100%)
TUSK_SAMPLING_RATE=1.0 npm start
TUSK_RECORDING_SAMPLING_RATE=1.0 npm start

# Record 10% of requests
TUSK_SAMPLING_RATE=0.1 npm start
TUSK_RECORDING_SAMPLING_RATE=0.1 npm start
```

`TUSK_SAMPLING_RATE` is still accepted as a backward-compatible alias, but `TUSK_RECORDING_SAMPLING_RATE` is the canonical variable going forward.

If `recording.sampling.mode: adaptive` is enabled in `.tusk/config.yaml`, this environment variable still only changes the base rate; adaptive load shedding remains active.

For more details on sampling rate configuration methods and precedence, see the [Initialization Guide](./initialization.md#3-configure-sampling-rate).

## TUSK_USE_RUST_CORE
Expand Down
88 changes: 72 additions & 16 deletions docs/initialization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ export { TuskDrift };
<td><code>samplingRate</code></td>
<td><code>number</code></td>
<td><code>1.0</code></td>
<td>Override sampling rate (0.0 - 1.0) for recording. Takes precedence over <code>TUSK_SAMPLING_RATE</code> env var and config file.</td>
<td>Override the base sampling rate (0.0 - 1.0) for recording. Takes precedence over <code>TUSK_RECORDING_SAMPLING_RATE</code> and config file base-rate settings. Does not change <code>recording.sampling.mode</code>.</td>
</tr>
<tr>
<td><code>registerEsmLoaderHooks</code></td>
Expand Down Expand Up @@ -137,17 +137,31 @@ For ESM applications, you **cannot** control import order within your applicatio

### 3. Configure Sampling Rate

The sampling rate determines what percentage of requests are recorded during replay tests. Tusk Drift supports three ways to configure the sampling rate, with the following precedence (highest to lowest):
Sampling controls what percentage of inbound requests are recorded in `RECORD` mode.

1. **Init Parameter**
2. **Environment Variable** (`TUSK_SAMPLING_RATE`)
3. **Configuration File** (`.tusk/config.yaml`)
Tusk Drift supports two sampling modes in `.tusk/config.yaml`:

If not specified, the default sampling rate is `1.0` (100%).
- `fixed`: record requests at a constant base rate.
- `adaptive`: start from a base rate and automatically shed load when queue pressure, export failures, export timeouts, event loop lag, or memory pressure indicate the SDK should back off. In severe conditions the SDK can temporarily pause recording entirely.

#### Method 1: Init Parameter (Programmatic Override)
Sampling configuration is resolved in two layers:

Set the sampling rate directly in your initialization code:
1. **Base rate precedence** (highest to lowest):
- `TuskDrift.initialize({ samplingRate: ... })`
- `TUSK_RECORDING_SAMPLING_RATE`
- legacy alias `TUSK_SAMPLING_RATE`
- `.tusk/config.yaml` `recording.sampling.base_rate`
- `.tusk/config.yaml` legacy `recording.sampling_rate`
- default base rate `1.0`
2. **Mode and minimum rate**:
- `recording.sampling.mode` comes from `.tusk/config.yaml` and defaults to `fixed`
- `recording.sampling.min_rate` is only used in `adaptive` mode and defaults to `0.001` when omitted

> **Note:** Requests before `TuskDrift.markAppAsReady()` are always recorded. Sampling applies to normal inbound traffic after startup.

#### Method 1: Init Parameter (Programmatic Base-Rate Override)

Set the base sampling rate directly in your initialization code:

```typescript
TuskDrift.initialize({
Expand All @@ -159,29 +173,53 @@ TuskDrift.initialize({

#### Method 2: Environment Variable

Set the `TUSK_SAMPLING_RATE` environment variable:
Set the `TUSK_RECORDING_SAMPLING_RATE` environment variable to override the base sampling rate:

```bash
# Development - record everything
TUSK_SAMPLING_RATE=1.0 npm run dev
TUSK_RECORDING_SAMPLING_RATE=1.0 npm run dev

# Production - sample 10% of requests
TUSK_SAMPLING_RATE=0.1 npm start
TUSK_RECORDING_SAMPLING_RATE=0.1 npm start
```

`TUSK_SAMPLING_RATE` is still supported as a backward-compatible alias, but new setups should prefer `TUSK_RECORDING_SAMPLING_RATE`.

#### Method 3: Configuration File

Update the configuration file `.tusk/config.yaml` to include a `recording` section. Example `recording` configuration:
Use the nested `recording.sampling` config to choose `fixed` vs `adaptive` mode and set the base/minimum rates.

```yaml
# ... existing configuration ...

recording:
sampling_rate: 0.1
sampling:
mode: fixed
base_rate: 0.1
export_spans: true
enable_env_var_recording: true
```

**Adaptive sampling example:**

```yaml
# ... existing configuration ...

recording:
sampling:
mode: adaptive
base_rate: 0.25
min_rate: 0.01
export_spans: true
```

**Legacy config still supported:**

```yaml
recording:
sampling_rate: 0.1
```

#### Additional Recording Configuration Options

<table>
Expand All @@ -195,10 +233,28 @@ recording:
</thead>
<tbody>
<tr>
<td><code>sampling_rate</code></td>
<td><code>sampling.mode</code></td>
<td><code>"fixed" | "adaptive"</code></td>
<td><code>"fixed"</code></td>
<td>Selects constant sampling or adaptive load shedding.</td>
</tr>
<tr>
<td><code>sampling.base_rate</code></td>
<td><code>number</code></td>
<td><code>1.0</code></td>
<td>The sampling rate (0.0 - 1.0). 1.0 means 100% of requests are recorded, 0.0 means 0% of requests are recorded.</td>
<td>The base sampling rate (0.0 - 1.0). This is the preferred config key and can be overridden by <code>TUSK_RECORDING_SAMPLING_RATE</code> or the <code>samplingRate</code> init parameter.</td>
</tr>
<tr>
<td><code>sampling.min_rate</code></td>
<td><code>number</code></td>
<td><code>0.001</code> in <code>adaptive</code> mode</td>
<td>The minimum steady-state sampling rate for adaptive mode. In critical conditions the SDK can still temporarily pause recording.</td>
</tr>
<tr>
<td><code>sampling_rate</code></td>
<td><code>number</code></td>
<td><code>None</code></td>
<td>Legacy fallback for the base sampling rate. Still supported for backward compatibility, but <code>recording.sampling.base_rate</code> is preferred.</td>
</tr>
<tr>
<td><code>export_spans</code></td>
Expand Down Expand Up @@ -249,7 +305,7 @@ In rare cases, the wrapping can cause issues with instrumented packages:

If you encounter errors like:

```
```text
SyntaxError: The requested module '...' does not provide an export named '...'
(node:1234) Error: 'import-in-the-middle' failed to wrap 'file://../../path/to/file.js'
```
Expand Down
86 changes: 71 additions & 15 deletions docs/nextjs-initialization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,7 @@ More context on setting up instrumentations for Next.js apps can be found [here]
<td><code>samplingRate</code></td>
<td><code>number</code></td>
<td><code>1.0</code></td>
<td>Override sampling rate (0.0 - 1.0) for recording. Takes precedence over <code>TUSK_SAMPLING_RATE</code> env var and config file.</td>
<td>Override the base sampling rate (0.0 - 1.0) for recording. Takes precedence over <code>TUSK_RECORDING_SAMPLING_RATE</code> and config file base-rate settings. Does not change <code>recording.sampling.mode</code>.</td>
</tr>
</tbody>
</table>
Expand All @@ -184,17 +184,31 @@ More context on setting up instrumentations for Next.js apps can be found [here]

## Step 3: Configure Sampling Rate

The sampling rate determines what percentage of requests are recorded during replay tests. Tusk Drift supports three ways to configure the sampling rate, with the following precedence (highest to lowest):
Sampling controls what percentage of inbound requests are recorded in `RECORD` mode.

1. **Init Parameter**
2. **Environment Variable** (`TUSK_SAMPLING_RATE`)
3. **Configuration File** (`.tusk/config.yaml`)
Tusk Drift supports two sampling modes in `.tusk/config.yaml`:

If not specified, the default sampling rate is `1.0` (100%).
- `fixed`: record requests at a constant base rate.
- `adaptive`: start from a base rate and automatically shed load when queue pressure, export failures, export timeouts, event loop lag, or memory pressure indicate the SDK should back off. In severe conditions the SDK can temporarily pause recording entirely.

Sampling configuration is resolved in two layers:

1. **Base rate precedence** (highest to lowest):
- `TuskDrift.initialize({ samplingRate: ... })`
- `TUSK_RECORDING_SAMPLING_RATE`
- legacy alias `TUSK_SAMPLING_RATE`
- `.tusk/config.yaml` `recording.sampling.base_rate`
- `.tusk/config.yaml` legacy `recording.sampling_rate`
- default base rate `1.0`
2. **Mode and minimum rate**:
- `recording.sampling.mode` comes from `.tusk/config.yaml` and defaults to `fixed`
- `recording.sampling.min_rate` is only used in `adaptive` mode and defaults to `0.001` when omitted

> **Note:** Requests before `TuskDrift.markAppAsReady()` are always recorded. Sampling applies to normal inbound traffic after startup.
Copy link
Copy Markdown
Contributor

@cubic-dev-ai cubic-dev-ai bot Apr 11, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: The startup note overstates pre-ready capture semantics. It says all requests before markAppAsReady() are always recorded, but this feature is described as preserving only the first inbound pre-app-start request.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At docs/nextjs-initialization.md, line 207:

<comment>The startup note overstates pre-ready capture semantics. It says all requests before `markAppAsReady()` are always recorded, but this feature is described as preserving only the first inbound pre-app-start request.</comment>

<file context>
@@ -184,17 +184,31 @@ More context on setting up instrumentations for Next.js apps can be found [here]
+   - `recording.sampling.mode` comes from `.tusk/config.yaml` and defaults to `fixed`
+   - `recording.sampling.min_rate` is only used in `adaptive` mode and defaults to `0.001` when omitted
+
+> **Note:** Requests before `TuskDrift.markAppAsReady()` are always recorded. Sampling applies to normal inbound traffic after startup.
 
 ### Method 1: Init Parameter
</file context>
Suggested change
> **Note:** Requests before `TuskDrift.markAppAsReady()` are always recorded. Sampling applies to normal inbound traffic after startup.
> **Note:** The first inbound request before the SDK marks the app ready is always recorded. Sampling applies to normal inbound traffic after startup.
Fix with Cubic


### Method 1: Init Parameter

Set the sampling rate directly in your initialization code:
Set the base sampling rate directly in your initialization code:

```typescript
// instrumentation.ts
Expand All @@ -215,29 +229,53 @@ export async function register() {

### Method 2: Environment Variable

Set the `TUSK_SAMPLING_RATE` environment variable:
Set the `TUSK_RECORDING_SAMPLING_RATE` environment variable to override the base sampling rate:

```bash
# Development - record everything
TUSK_SAMPLING_RATE=1.0 npm run dev
TUSK_RECORDING_SAMPLING_RATE=1.0 npm run dev

# Production - sample 10% of requests
TUSK_SAMPLING_RATE=0.1 npm start
TUSK_RECORDING_SAMPLING_RATE=0.1 npm start
```

`TUSK_SAMPLING_RATE` is still supported as a backward-compatible alias, but new setups should prefer `TUSK_RECORDING_SAMPLING_RATE`.

### Method 3: Configuration File

Update the `.tusk/config.yaml` file in your project root to include recording configuration:
Use the nested `recording.sampling` config to choose `fixed` vs `adaptive` mode and set the base/minimum rates.

```yaml
# ... existing configuration ...

recording:
sampling_rate: 0.1
sampling:
mode: fixed
base_rate: 0.1
export_spans: true
enable_env_var_recording: true
```

**Adaptive sampling example:**

```yaml
# ... existing configuration ...

recording:
sampling:
mode: adaptive
base_rate: 0.25
min_rate: 0.01
export_spans: true
```

**Legacy config still supported:**

```yaml
recording:
sampling_rate: 0.1
```

### Additional Recording Configuration Options

<table>
Expand All @@ -251,10 +289,28 @@ recording:
</thead>
<tbody>
<tr>
<td><code>sampling_rate</code></td>
<td><code>sampling.mode</code></td>
<td><code>"fixed" | "adaptive"</code></td>
<td><code>"fixed"</code></td>
<td>Selects constant sampling or adaptive load shedding.</td>
</tr>
<tr>
<td><code>sampling.base_rate</code></td>
<td><code>number</code></td>
<td><code>1.0</code></td>
<td>The sampling rate (0.0 - 1.0). 1.0 means 100% of requests are recorded, 0.0 means no requests are recorded.</td>
<td>The base sampling rate (0.0 - 1.0). This is the preferred config key and can be overridden by <code>TUSK_RECORDING_SAMPLING_RATE</code> or the <code>samplingRate</code> init parameter.</td>
</tr>
<tr>
<td><code>sampling.min_rate</code></td>
<td><code>number</code></td>
<td><code>0.001</code> in <code>adaptive</code> mode</td>
<td>The minimum steady-state sampling rate for adaptive mode. In critical conditions the SDK can still temporarily pause recording.</td>
</tr>
<tr>
<td><code>sampling_rate</code></td>
<td><code>number</code></td>
<td><code>None</code></td>
<td>Legacy fallback for the base sampling rate. Still supported for backward compatibility, but <code>recording.sampling.base_rate</code> is preferred.</td>
</tr>
<tr>
<td><code>export_spans</code></td>
Expand All @@ -270,7 +326,7 @@ recording:
</tr>
</tbody>
</table>

## Troubleshooting

### Instrumentation not working
Expand Down
2 changes: 1 addition & 1 deletion docs/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Let's walk through recording and replaying your first trace:

## Step 1: Set sampling rate to 1.0

Set the `sampling_rate` in `.tusk/config.yaml` to 1.0 to ensure that all requests are recorded.
Set `recording.sampling.mode: fixed` and `recording.sampling.base_rate: 1.0` in `.tusk/config.yaml` to ensure that all requests are recorded.

## Step 2: Start server in record mode

Expand Down
6 changes: 4 additions & 2 deletions docs/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,10 @@

1. **Check sampling rate**: Verify your sampling rate configuration is set to 1.0 for 100% recording. The SDK checks in this order:
- `samplingRate` in `TuskDrift.initialize()` (highest priority)
- `TUSK_SAMPLING_RATE` environment variable
- `sampling_rate` in `.tusk/config.yaml`
- `TUSK_RECORDING_SAMPLING_RATE` environment variable
- legacy alias `TUSK_SAMPLING_RATE`
- `recording.sampling.base_rate` in `.tusk/config.yaml`
- legacy `recording.sampling_rate` in `.tusk/config.yaml`
- Default: 1.0
2. **Verify app readiness**: Make sure you're calling `TuskDrift.markAppAsReady()`
3. **Use debug mode in SDK**: Add `logLevel: 'debug'` to the initialization parameters
Expand Down
Loading
Loading