feat: add adaptive sampling to python sdk (#90)

Author: jy-tan

docs/environment-variables.md

@@ -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.
+Controls the base recording rate used 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 `sampling_rate` 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 `sampling_rate` 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 python app.py
+TUSK_RECORDING_SAMPLING_RATE=1.0 python app.py
 
 # Record 10% of requests
-TUSK_SAMPLING_RATE=0.1 python app.py
+TUSK_RECORDING_SAMPLING_RATE=0.1 python app.py
 ```
 
+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.
+
+`TUSK_RECORDING_SAMPLING_RATE` is the canonical variable, but `TUSK_SAMPLING_RATE` is still accepted as a backward-compatible alias.
+
 For more details on sampling rate configuration methods and precedence, see the [Initialization Guide](./initialization.md#configure-sampling-rate).
 
 ## Rust Core Flags

docs/initialization.md

@@ -73,8 +73,8 @@ Create an initialization file or add the SDK initialization to your application
     <tr>
       <td><code>sampling_rate</code></td>
       <td><code>float</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><code>None</code></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>
@@ -172,50 +172,91 @@ if __name__ == "__main__":
 
 ## 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.
+
+Tusk Drift supports two sampling modes in `.tusk/config.yaml`:
+
+- `fixed`: record requests at a constant base rate.
+- `adaptive`: start from a base rate and automatically shed load when queue pressure, export failures, 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. **Init Parameter**
-2. **Environment Variable** (`TUSK_SAMPLING_RATE`)
-3. **Configuration File** (`.tusk/config.yaml`)
+1. **Base rate precedence** (highest to lowest):
+   - `TuskDrift.initialize(sampling_rate=...)`
+   - `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
 
-If not specified, the default sampling rate is `1.0` (100%).
+> [!NOTE]
+> Requests before `sdk.mark_app_as_ready()` are always recorded. Sampling applies to normal inbound traffic after startup.
 
-### Method 1: Init Parameter (Programmatic Override)
+### Method 1: Init Parameter (Programmatic Base-Rate Override)
 
-Set the sampling rate directly in your initialization code:
+Set the base sampling rate directly in your initialization code:
 
 ```python
 sdk = TuskDrift.initialize(
     api_key=os.environ.get("TUSK_API_KEY"),
-    sampling_rate=0.1,  # 10% of requests
+    sampling_rate=0.1,  # Base rate: 10% of requests
 )
 ```
 
 ### 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 python app.py
+TUSK_RECORDING_SAMPLING_RATE=1.0 python app.py
 
 # Production - sample 10% of requests
-TUSK_SAMPLING_RATE=0.1 python app.py
+TUSK_RECORDING_SAMPLING_RATE=0.1 python app.py
 ```
 
+`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:
+Use the nested `recording.sampling` config to choose `fixed` vs `adaptive` mode and set the base/minimum rates.
+
+**Fixed sampling example:**
 
 ```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
+```
+
 ### Recording Configuration Options
 
 <table>
@@ -229,10 +270,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>float</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>sampling_rate</code> init parameter.</td>
+    </tr>
+    <tr>
+      <td><code>sampling.min_rate</code></td>
+      <td><code>float</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>float</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>

docs/quickstart.md

@@ -2,9 +2,18 @@
 
 Let's walk through recording and replaying your first trace:
 
-## Step 1: Set sampling rate to 1.0
+## Step 1: Set fixed sampling to 1.0
 
-Set the `sampling_rate` in `.tusk/config.yaml` to 1.0 to ensure that all requests are recorded.
+Update `.tusk/config.yaml` so your first recording captures every request:
+
+```yaml
+recording:
+  sampling:
+    mode: fixed
+    base_rate: 1.0
+```
+
+Legacy `recording.sampling_rate: 1.0` still works, but `recording.sampling` is the preferred config shape.
 
 ## Step 2: Start server in record mode