Skip to content

Commit a99019e

Browse files
committed
Standardize to use TUSK_RECORDING_SAMPLING_RATE
1 parent 0d4844d commit a99019e

20 files changed

Lines changed: 98 additions & 29 deletions

File tree

docs/environment-variables.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ Your Tusk Drift API key, required when using Tusk Cloud for storing and managing
110110

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

113-
## TUSK_SAMPLING_RATE
113+
## TUSK_RECORDING_SAMPLING_RATE
114114

115115
Controls the base recording rate used during trace collection.
116116

@@ -123,14 +123,16 @@ Controls the base recording rate used during trace collection.
123123

124124
```bash
125125
# Record all requests (100%)
126-
TUSK_SAMPLING_RATE=1.0 python app.py
126+
TUSK_RECORDING_SAMPLING_RATE=1.0 python app.py
127127

128128
# Record 10% of requests
129-
TUSK_SAMPLING_RATE=0.1 python app.py
129+
TUSK_RECORDING_SAMPLING_RATE=0.1 python app.py
130130
```
131131

132132
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.
133133

134+
`TUSK_RECORDING_SAMPLING_RATE` is the canonical variable, but `TUSK_SAMPLING_RATE` is still accepted as a backward-compatible alias.
135+
134136
For more details on sampling rate configuration methods and precedence, see the [Initialization Guide](./initialization.md#configure-sampling-rate).
135137

136138
## Rust Core Flags

docs/initialization.md

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ Create an initialization file or add the SDK initialization to your application
7474
<td><code>sampling_rate</code></td>
7575
<td><code>float</code></td>
7676
<td><code>None</code></td>
77-
<td>Override the base sampling rate (0.0 - 1.0) for recording. Takes precedence over <code>TUSK_SAMPLING_RATE</code> and config file base-rate settings. Does not change <code>recording.sampling.mode</code>.</td>
77+
<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>
7878
</tr>
7979
</tbody>
8080
</table>
@@ -183,7 +183,8 @@ Sampling configuration is resolved in two layers:
183183

184184
1. **Base rate precedence** (highest to lowest):
185185
- `TuskDrift.initialize(sampling_rate=...)`
186-
- `TUSK_SAMPLING_RATE`
186+
- `TUSK_RECORDING_SAMPLING_RATE`
187+
- legacy alias `TUSK_SAMPLING_RATE`
187188
- `.tusk/config.yaml` `recording.sampling.base_rate`
188189
- `.tusk/config.yaml` legacy `recording.sampling_rate`
189190
- default base rate `1.0`
@@ -207,16 +208,18 @@ sdk = TuskDrift.initialize(
207208

208209
### Method 2: Environment Variable
209210

210-
Set the `TUSK_SAMPLING_RATE` environment variable to override the base sampling rate:
211+
Set the `TUSK_RECORDING_SAMPLING_RATE` environment variable to override the base sampling rate:
211212

212213
```bash
213214
# Development - record everything
214-
TUSK_SAMPLING_RATE=1.0 python app.py
215+
TUSK_RECORDING_SAMPLING_RATE=1.0 python app.py
215216

216217
# Production - sample 10% of requests
217-
TUSK_SAMPLING_RATE=0.1 python app.py
218+
TUSK_RECORDING_SAMPLING_RATE=0.1 python app.py
218219
```
219220

221+
`TUSK_SAMPLING_RATE` is still supported as a backward-compatible alias, but new setups should prefer `TUSK_RECORDING_SAMPLING_RATE`.
222+
220223
### Method 3: Configuration File
221224

222225
Use the nested `recording.sampling` config to choose `fixed` vs `adaptive` mode and set the base/minimum rates.
@@ -276,7 +279,7 @@ recording:
276279
<td><code>sampling.base_rate</code></td>
277280
<td><code>float</code></td>
278281
<td><code>1.0</code></td>
279-
<td>The base sampling rate (0.0 - 1.0). This is the preferred config key and can be overridden by <code>TUSK_SAMPLING_RATE</code> or the <code>sampling_rate</code> init parameter.</td>
282+
<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>sampling_rate</code> init parameter.</td>
280283
</tr>
281284
<tr>
282285
<td><code>sampling.min_rate</code></td>

drift/core/drift_sdk.py

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -358,16 +358,20 @@ def _determine_sampling_config(self, init_param: float | None) -> ResolvedSampli
358358
base_rate = validated
359359

360360
if base_rate is None:
361-
env_rate = os.environ.get("TUSK_SAMPLING_RATE")
362-
if env_rate is not None:
361+
for env_key in ("TUSK_RECORDING_SAMPLING_RATE", "TUSK_SAMPLING_RATE"):
362+
env_rate = os.environ.get(env_key)
363+
if env_rate is None:
364+
continue
365+
363366
try:
364367
parsed = float(env_rate)
365-
validated = validate_sampling_rate(parsed, "TUSK_SAMPLING_RATE env var")
368+
validated = validate_sampling_rate(parsed, f"{env_key} env var")
366369
if validated is not None:
367-
logger.debug(f"Using sampling rate from env var: {validated}")
370+
logger.debug(f"Using sampling rate from {env_key} env var: {validated}")
368371
base_rate = validated
372+
break
369373
except ValueError:
370-
logger.warning(f"Invalid TUSK_SAMPLING_RATE env var: {env_rate}")
374+
logger.warning(f"Invalid {env_key} env var: {env_rate}")
371375

372376
if base_rate is None and config_sampling and config_sampling.base_rate is not None:
373377
validated = validate_sampling_rate(config_sampling.base_rate, "config file recording.sampling.base_rate")

drift/instrumentation/aiohttp/e2e-tests/docker-compose.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ services:
2727
- BENCHMARKS=${BENCHMARKS:-}
2828
- BENCHMARK_DURATION=${BENCHMARK_DURATION:-10}
2929
- BENCHMARK_WARMUP=${BENCHMARK_WARMUP:-3}
30+
- TUSK_RECORDING_SAMPLING_RATE=${TUSK_RECORDING_SAMPLING_RATE:-}
3031
- TUSK_SAMPLING_RATE=${TUSK_SAMPLING_RATE:-}
3132
- USE_MOCK_EXTERNALS=${USE_MOCK_EXTERNALS:-1}
3233
- MOCK_SERVER_BASE_URL=${MOCK_SERVER_BASE_URL:-http://mock-upstream:8081}

drift/instrumentation/django/e2e-tests/docker-compose.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ services:
2828
- BENCHMARKS=${BENCHMARKS:-}
2929
- BENCHMARK_DURATION=${BENCHMARK_DURATION:-10}
3030
- BENCHMARK_WARMUP=${BENCHMARK_WARMUP:-3}
31+
- TUSK_RECORDING_SAMPLING_RATE=${TUSK_RECORDING_SAMPLING_RATE:-}
3132
- TUSK_SAMPLING_RATE=${TUSK_SAMPLING_RATE:-}
3233
- USE_MOCK_EXTERNALS=${USE_MOCK_EXTERNALS:-1}
3334
- MOCK_SERVER_BASE_URL=${MOCK_SERVER_BASE_URL:-http://mock-upstream:8081}

drift/instrumentation/fastapi/e2e-tests/docker-compose.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ services:
2727
- BENCHMARKS=${BENCHMARKS:-}
2828
- BENCHMARK_DURATION=${BENCHMARK_DURATION:-10}
2929
- BENCHMARK_WARMUP=${BENCHMARK_WARMUP:-3}
30+
- TUSK_RECORDING_SAMPLING_RATE=${TUSK_RECORDING_SAMPLING_RATE:-}
3031
- TUSK_SAMPLING_RATE=${TUSK_SAMPLING_RATE:-}
3132
- USE_MOCK_EXTERNALS=${USE_MOCK_EXTERNALS:-1}
3233
- MOCK_SERVER_BASE_URL=${MOCK_SERVER_BASE_URL:-http://mock-upstream:8081}

drift/instrumentation/flask/e2e-tests/docker-compose.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ services:
2727
- BENCHMARKS=${BENCHMARKS:-}
2828
- BENCHMARK_DURATION=${BENCHMARK_DURATION:-10}
2929
- BENCHMARK_WARMUP=${BENCHMARK_WARMUP:-3}
30+
- TUSK_RECORDING_SAMPLING_RATE=${TUSK_RECORDING_SAMPLING_RATE:-}
3031
- TUSK_SAMPLING_RATE=${TUSK_SAMPLING_RATE:-}
3132
- USE_MOCK_EXTERNALS=${USE_MOCK_EXTERNALS:-1}
3233
- MOCK_SERVER_BASE_URL=${MOCK_SERVER_BASE_URL:-http://mock-upstream:8081}

drift/instrumentation/grpc/e2e-tests/docker-compose.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ services:
1818
- BENCHMARKS=${BENCHMARKS:-}
1919
- BENCHMARK_DURATION=${BENCHMARK_DURATION:-10}
2020
- BENCHMARK_WARMUP=${BENCHMARK_WARMUP:-3}
21+
- TUSK_RECORDING_SAMPLING_RATE=${TUSK_RECORDING_SAMPLING_RATE:-}
2122
- TUSK_SAMPLING_RATE=${TUSK_SAMPLING_RATE:-}
2223
working_dir: /app
2324
volumes:

drift/instrumentation/httpx/e2e-tests/docker-compose.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ services:
2727
- BENCHMARKS=${BENCHMARKS:-}
2828
- BENCHMARK_DURATION=${BENCHMARK_DURATION:-10}
2929
- BENCHMARK_WARMUP=${BENCHMARK_WARMUP:-3}
30+
- TUSK_RECORDING_SAMPLING_RATE=${TUSK_RECORDING_SAMPLING_RATE:-}
3031
- TUSK_SAMPLING_RATE=${TUSK_SAMPLING_RATE:-}
3132
- USE_MOCK_EXTERNALS=${USE_MOCK_EXTERNALS:-1}
3233
- MOCK_SERVER_BASE_URL=${MOCK_SERVER_BASE_URL:-http://mock-upstream:8081}

drift/instrumentation/psycopg/e2e-tests/docker-compose.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ services:
3838
- BENCHMARKS=${BENCHMARKS:-}
3939
- BENCHMARK_DURATION=${BENCHMARK_DURATION:-10}
4040
- BENCHMARK_WARMUP=${BENCHMARK_WARMUP:-3}
41+
- TUSK_RECORDING_SAMPLING_RATE=${TUSK_RECORDING_SAMPLING_RATE:-}
4142
- TUSK_SAMPLING_RATE=${TUSK_SAMPLING_RATE:-}
4243
working_dir: /app
4344
volumes:

0 commit comments

Comments
 (0)