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.
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, set sampling rate to 1.0. After testing, we recommend a sampling rate between 0.01-0.1. 
# ... existing configuration ...

recording:
  sampling_rate: 0.1
  export_spans: true
  enable_env_var_recording: true

​
Configuration Options

OptionTypeDefaultDescription
sampling_ratenumber1.0The sampling rate (0.0 - 1.0). 1.0 means 100% of requests are recorded, 0.0 means 0% of requests are recorded.
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.