Skip to main content

​
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

For ESM applications, you cannot control import order within your application code because all imports are hoisted. Instead, use the --import flag. Update your package.json scripts: 
{
  "scripts": {
    "dev": "node --import ./dist/tuskDriftInit.js dist/server.js",
    "dev:record": "TUSK_DRIFT_MODE=RECORD node --import ./dist/tuskDriftInit.js dist/server.js"
  }
}
Why --import is required for ESM: In ESM, all import statements are hoisted and evaluated before any code runs, making it impossible to control import order within a file.
The --import flag ensures SDK initialization happens in a separate phase before your application code loads, guaranteeing proper module interception.

​
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: 
// 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.