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
| Option | Type | Default | Description |
|---|
apiKey | string | Required if using Tusk Cloud | Your Tusk Drift API key. |
env | string | process.env.NODE_ENV | The environment name. |
logLevel | ’silent’ | ‘error’ | ‘warn’ | ‘info’ | ‘debug' | 'info’ | The logging level. |
samplingRate | number | 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. |
registerEsmLoaderHooks | boolean | true | Automatically 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
| Option | Type | Default | Description |
|---|
sampling.mode | string | ”fixed” | Selects constant sampling or adaptive load shedding. |
sampling.base_rate | number | 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 | number | 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 | boolean | true | Controls whether the SDK emits adaptive-sampling transition logs. Can
also be overridden by
TUSK_RECORDING_SAMPLING_LOG_TRANSITIONS. |
sampling_rate | number | None | Legacy alias for recording.sampling.base_rate. Still
supported for backward compatibility. |
export_spans | boolean | 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 | boolean | false | Whether 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");
});
