|
| 1 | +# Environment Variables |
| 2 | + |
| 3 | +This guide covers the environment variables that can be set when using the Tusk Drift SDK. |
| 4 | + |
| 5 | +## TUSK_DRIFT_MODE |
| 6 | + |
| 7 | +The `TUSK_DRIFT_MODE` environment variable controls how the SDK operates in your application. |
| 8 | + |
| 9 | +### Available Modes |
| 10 | + |
| 11 | +| Mode | Description | When to Use | |
| 12 | +| ---------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- | |
| 13 | +| `RECORD` | Records traces for all instrumented operations | Set this in environments where you want to capture API traces (e.g., staging, production) | |
| 14 | +| `REPLAY` | Replays previously recorded traces | Automatically set by the Tusk CLI when running `tusk run` - you should NOT set this manually | |
| 15 | +| `DISABLED` | Disables all instrumentation and recording | Use when you want to completely disable Tusk with no performance impact | |
| 16 | +| Unset | Same as `DISABLED` - no instrumentation or recording | Default state when the variable is not set | |
| 17 | + |
| 18 | +### Important Notes |
| 19 | + |
| 20 | +**Recording Traces:** |
| 21 | + |
| 22 | +- Set `TUSK_DRIFT_MODE=RECORD` in any environment where you want to record traces |
| 23 | +- This is typically staging, production, or local development environments |
| 24 | +- Traces will be saved according to your `recording` configuration in `.tusk/config.yaml` |
| 25 | + |
| 26 | +**Replaying Traces:** |
| 27 | + |
| 28 | +- `TUSK_DRIFT_MODE` is automatically set to `REPLAY` by the Tusk CLI when you run `tusk run` |
| 29 | +- **Do NOT** manually set `TUSK_DRIFT_MODE=REPLAY` in your application startup commands |
| 30 | +- The start command specified in your `.tusk/config.yaml` should NOT cause `TUSK_DRIFT_MODE` to be set to anything - the CLI handles this automatically |
| 31 | + |
| 32 | +**Disabling Tusk:** |
| 33 | + |
| 34 | +- If `TUSK_DRIFT_MODE` is unset or set to `DISABLED`, the SDK will not add any instrumentation |
| 35 | +- No data will be recorded and there should be **no performance impact** |
| 36 | +- This is useful for environments where you don't need Tusk functionality |
| 37 | + |
| 38 | +### Examples |
| 39 | + |
| 40 | +**Recording in development:** |
| 41 | + |
| 42 | +```bash |
| 43 | +TUSK_DRIFT_MODE=RECORD python app.py |
| 44 | +``` |
| 45 | + |
| 46 | +**Recording in production (via environment variable):** |
| 47 | + |
| 48 | +```bash |
| 49 | +# In your .env file or deployment configuration |
| 50 | +TUSK_DRIFT_MODE=RECORD |
| 51 | +``` |
| 52 | + |
| 53 | +**Start command in config.yaml (correct):** |
| 54 | + |
| 55 | +```yaml |
| 56 | +# .tusk/config.yaml |
| 57 | +start_command: "python app.py" # Do NOT include TUSK_DRIFT_MODE here |
| 58 | +``` |
| 59 | +
|
| 60 | +**Replaying traces (handled by CLI):** |
| 61 | +
|
| 62 | +```bash |
| 63 | +# The CLI automatically sets TUSK_DRIFT_MODE=REPLAY |
| 64 | +tusk run |
| 65 | +``` |
| 66 | + |
| 67 | +**Disabling Tusk:** |
| 68 | + |
| 69 | +```bash |
| 70 | +# Either unset the variable or explicitly disable |
| 71 | +TUSK_DRIFT_MODE=DISABLED python app.py |
| 72 | + |
| 73 | +# Or simply don't set it at all |
| 74 | +python app.py |
| 75 | +``` |
| 76 | + |
| 77 | +## TUSK_API_KEY |
| 78 | + |
| 79 | +Your Tusk Drift API key, required when using Tusk Cloud for storing and managing traces. |
| 80 | + |
| 81 | +- **Required:** Only if using Tusk Cloud (not needed for local-only trace storage) |
| 82 | +- **Where to get it:** [Tusk Drift Dashboard](https://usetusk.ai/app/settings/api-keys) |
| 83 | + |
| 84 | +### How to Set |
| 85 | + |
| 86 | +**For Recording:** |
| 87 | + |
| 88 | +- Must be provided in the `TuskDrift.initialize()` call: |
| 89 | + |
| 90 | + ```python |
| 91 | + sdk = TuskDrift.initialize( |
| 92 | + api_key=os.environ.get("TUSK_API_KEY"), # or hard-coded for non-production |
| 93 | + # ... other options |
| 94 | + ) |
| 95 | + ``` |
| 96 | + |
| 97 | +**For Replay:** |
| 98 | + |
| 99 | +- Can be set as an environment variable: |
| 100 | + |
| 101 | + ```bash |
| 102 | + TUSK_API_KEY=your-api-key-here tusk run |
| 103 | + ``` |
| 104 | + |
| 105 | +- Or use the Tusk CLI login command (recommended): |
| 106 | + |
| 107 | + ```bash |
| 108 | + tusk auth login |
| 109 | + ``` |
| 110 | + |
| 111 | + This will securely store your auth key for future replay sessions. |
| 112 | + |
| 113 | +## TUSK_SAMPLING_RATE |
| 114 | + |
| 115 | +Controls what percentage of requests are recorded during trace collection. |
| 116 | + |
| 117 | +- **Type:** Number between 0.0 and 1.0 |
| 118 | +- **Default:** 1.0 (100% of requests) |
| 119 | +- **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` |
| 120 | + |
| 121 | +**Examples:** |
| 122 | + |
| 123 | +```bash |
| 124 | +# Record all requests (100%) |
| 125 | +TUSK_SAMPLING_RATE=1.0 python app.py |
| 126 | + |
| 127 | +# Record 10% of requests |
| 128 | +TUSK_SAMPLING_RATE=0.1 python app.py |
| 129 | +``` |
| 130 | + |
| 131 | +For more details on sampling rate configuration methods and precedence, see the [Initialization Guide](./initialization.md#configure-sampling-rate). |
| 132 | + |
| 133 | +## Connection Variables |
| 134 | + |
| 135 | +These variables configure how the SDK connects to the Tusk CLI during replay: |
| 136 | + |
| 137 | +| Variable | Description | Default | |
| 138 | +| ------------------ | ----------------------------------- | ------------------------- | |
| 139 | +| `TUSK_MOCK_HOST` | CLI host for TCP connection | - | |
| 140 | +| `TUSK_MOCK_PORT` | CLI port for TCP connection | - | |
| 141 | +| `TUSK_MOCK_SOCKET` | Unix socket path for CLI connection | `/tmp/tusk-connect.sock` | |
| 142 | + |
| 143 | +These are typically set automatically by the Tusk CLI and do not need to be configured manually. |
| 144 | + |
| 145 | +--- |
| 146 | + |
| 147 | +## Related Documentation |
| 148 | + |
| 149 | +- [Initialization Guide](./initialization.md) - SDK initialization parameters and config file settings |
| 150 | +- [Quick Start Guide](./quickstart.md) - Record and replay your first trace |
0 commit comments