Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usetusk.ai/llms.txt

Use this file to discover all available pages before exploring further.

The code examples in this guide use import/export syntax. If your project is JavaScript, adapt the examples to use require()/module.exports instead.

​
1. Create init file

Create a tuskDriftInit.ts or tuskDriftInit.js file to initialize the Tusk Drift SDK. 
import { TuskDrift } from "@use-tusk/drift-node-sdk";

// Initialize SDK immediately
TuskDrift.initialize({
  // Add API key once you are initializing Cloud
  // apiKey: process.env.TUSK_DRIFT_API_KEY,
  env: process.env.NODE_ENV,
});

export { TuskDrift };

​
Initialization Parameters

OptionTypeDefaultDescription
apiKeystringRequired if using Tusk CloudYour Tusk Drift API key.
envstringprocess.env.NODE_ENVThe environment name.
logLevel’silent’ | ‘error’ | ‘warn’ | ‘info’ | ‘debug''info’The logging level.
samplingRatenumber1.0Override the base sampling rate (0.0 - 1.0) for recording. Takes precedence over TUSK_RECORDING_SAMPLING_RATE and config file base-rate settings.
registerEsmLoaderHooksbooleantrueAutomatically register ESM loader hooks for module interception. Set to false to disable if you encounter issues with specific instrumented packages.

​
2. Import SDK at application entry point

In your main server file (e.g., server.ts, index.ts, app.ts), import this file at the very top before any other imports. This ensures proper instrumentation of all dependencies. 
// e.g. server.ts
import { TuskDrift } from "./tuskDriftInit"; // MUST be the first import

// ... other imports ...

// Your application setup ...

​
3. Update recording configurations

Update the configuration file .tusk/config.yaml to include a recording section. If you’re testing Tusk Drift out locally for the first time, use fixed mode with a base rate of 1.0. After testing, we generally recommend adaptive mode with a base rate between 0.01 and 0.1. 
# ... 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
TUSK_RECORDING_SAMPLING_RATE overrides recording.sampling.base_rate. TUSK_SAMPLING_RATE is still supported as a legacy alias, and recording.sampling_rate remains a legacy config alias.

​
Configuration Options

OptionTypeDefaultDescription
sampling.modestring”fixed”Selects constant sampling or adaptive load shedding.
sampling.base_ratenumber1.0The 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_ratenumber0.001 in adaptive modeThe minimum steady-state sampling rate for adaptive mode. In critical conditions the SDK can still temporarily pause recording.
sampling.log_transitionsbooleantrueControls whether the SDK emits adaptive-sampling transition logs. Can also be overridden by TUSK_RECORDING_SAMPLING_LOG_TRANSITIONS.
sampling_ratenumberNoneLegacy alias for recording.sampling.base_rate. Still supported for backward compatibility.
export_spansbooleanfalseWhether to export spans to Tusk backend or local files ( .tusk/traces). If false, spans are only exported to local files.
enable_env_var_recordingbooleanfalseWhether to enable environment variable recording and replaying. Recommended if your application’s business logic depends on environment variables, as this ensures the most accurate replay behavior.

​
4. Mark the app as ready

Once your application is ready to accept requests, mark it as ready: 
// e.g. server.ts
import { TuskDrift } from "./tuskDriftInit";

// ... other imports ...

const app = express();

// Your application setup...

app.listen(8000, () => {
  // Mark app as ready for recording/replay
  TuskDrift.markAppAsReady();
  console.log("Server started and ready for Tusk Drift");
});
To record your first set of API tests with Tusk Drift, view this guide.