Python

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

Flask
FastAPI
Django

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()

2. Configure sampling

Tusk Drift supports both fixed sampling and adaptive sampling. In 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

The legacy 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")

The 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.

Get Started

Platform

Analytics API

1. Initialize the SDK

Initialization Parameters

Framework-Specific Setup

2. Configure sampling

Recording Configuration Options

3. Mark the app as ready

Get Started

Platform

Analytics API

Documentation Index

​1. Initialize the SDK

​Initialization Parameters

​Framework-Specific Setup

​2. Configure sampling

​Recording Configuration Options

​3. Mark the app as ready

1. Initialize the SDK

Initialization Parameters

Framework-Specific Setup

2. Configure sampling

Recording Configuration Options

3. Mark the app as ready