1. Initialize the SDK
Create an init file or add the SDK initialization to your application entry point. The SDK must be initialized before your application starts handling requests.
Ensure that TuskDrift is initialized before any other telemetry providers (e.g., OpenTelemetry, Sentry, etc.). If not, your existing telemetry may not work properly.
Initialization Parameters
| Option | Type | Default | Description |
|---|
api_key | str | Required if using Tusk Cloud | Your Tusk Drift API key. |
env | str | os.environ.get(“ENV”, “development”) | The environment name. |
log_level | ”silent” | “error” | “warn” | “info” | “debug" | "info” | The logging level. |
sampling_rate | float | 1.0 | Override the base sampling rate (0.0 - 1.0) for recording. Takes precedence over TUSK_RECORDING_SAMPLING_RATE and config file base-rate settings. |
See also: Environment Variables guide for detailed information about environment variables.
Framework-Specific Setup
import os
from flask import Flask
from drift import TuskDrift
# Initialize SDK BEFORE creating Flask app
sdk = TuskDrift.initialize(
api_key=os.environ.get("TUSK_API_KEY"),
env=os.environ.get("FLASK_ENV", "development"),
log_level="debug"
)
app = Flask(__name__)
@app.route("/")
def hello():
return "Hello, World!"
if __name__ == "__main__":
# Mark app as ready before starting server
sdk.mark_app_as_ready()
app.run(host="0.0.0.0", port=8000)
import os
import uvicorn
from fastapi import FastAPI
from drift import TuskDrift
# Initialize SDK BEFORE creating FastAPI app
sdk = TuskDrift.initialize(
api_key=os.environ.get("TUSK_API_KEY"),
env=os.environ.get("ENV", "development"),
log_level="debug"
)
app = FastAPI()
@app.get("/")
async def hello():
return {"message": "Hello, World!"}
if __name__ == "__main__":
# Mark app as ready before starting server
sdk.mark_app_as_ready()
uvicorn.run(app, host="0.0.0.0", port=8000)
For Django applications, initialize the SDK in your manage.py or WSGI/ASGI entry point:# manage.py
import os
import sys
# Initialize SDK BEFORE Django setup
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
from drift import TuskDrift
sdk = TuskDrift.initialize(
api_key=os.environ.get("TUSK_API_KEY"),
env=os.environ.get("DJANGO_ENV", "development"),
log_level="debug"
)
import django
django.setup()
# Mark app as ready
sdk.mark_app_as_ready()
def main():
from django.core.management import execute_from_command_line
execute_from_command_line(sys.argv)
if __name__ == "__main__":
main()
fixed mode,
the SDK records at a constant rate. In adaptive mode, the SDK starts from a
configured base rate and can temporarily reduce recording if local exporter or
runtime pressure increases.
The base sampling rate uses the following precedence (highest to lowest):
- Init Parameter (
sampling_rate)
- Environment Variable (
TUSK_RECORDING_SAMPLING_RATE, with TUSK_SAMPLING_RATE kept as a legacy alias)
- Configuration File (
recording.sampling.base_rate, or legacy recording.sampling_rate)
If not specified, the default base sampling rate is 1.0 (100%). The sampling
mode defaults to fixed.
Init Parameter
Environment Variable
Configuration File
Set the sampling rate directly in your initialization code:sdk = TuskDrift.initialize(
api_key=os.environ.get("TUSK_API_KEY"),
sampling_rate=0.1, # 10% of requests
)
Set the TUSK_RECORDING_SAMPLING_RATE environment variable:# Development - record everything
TUSK_RECORDING_SAMPLING_RATE=1.0 python app.py
# Production - sample 10% of requests
TUSK_RECORDING_SAMPLING_RATE=0.1 python app.py
Use the nested recording.sampling config to choose fixed vs adaptive mode:# ... existing configuration ...
recording:
sampling:
mode: adaptive
base_rate: 0.1
min_rate: 0.01
log_transitions: true
export_spans: true
enable_env_var_recording: true
recording.sampling_rate field is still supported as an alias
for recording.sampling.base_rate. Recording Configuration Options
| Option | Type | Default | Description |
|---|
sampling.mode | str | ”fixed” | Selects constant sampling or adaptive load shedding. |
sampling.base_rate | float | 1.0 | The base sampling rate (0.0 - 1.0). In fixed mode this is the effective rate. In adaptive mode the SDK may temporarily reduce below this base rate. |
sampling.min_rate | float | 0.001 in adaptive mode | The minimum steady-state sampling rate for adaptive mode. In critical conditions the SDK can still temporarily pause recording. |
sampling.log_transitions | bool | True | Controls whether the SDK emits adaptive-sampling transition logs. Can also be overridden by TUSK_RECORDING_SAMPLING_LOG_TRANSITIONS. |
sampling_rate | float | None | Legacy alias for recording.sampling.base_rate. Still supported for backward compatibility. |
export_spans | bool | false | Whether to export spans to Tusk backend or local files (.tusk/traces). If false, spans are only exported to local files. |
enable_env_var_recording | bool | false | Whether to enable environment variable recording and replaying. Recommended if your application’s business logic depends on environment variables. |
3. Mark the app as ready
Once your application has completed initialization (database connections, middleware setup, etc.), mark it as ready:
sdk = TuskDrift.initialize(
api_key=os.environ.get("TUSK_API_KEY"),
)
# Your application setup...
# Mark app as ready for recording/replay
sdk.mark_app_as_ready()
print("Server started and ready for Tusk Drift")
mark_app_as_ready() call signals to the SDK that your application is fully initialized and ready to handle requests. This ensures that traces are only recorded for requests that occur after your application is properly set up.
To record your first set of API tests with Tusk Drift, view this guide.