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({
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. |
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, 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
| Option | Type | Default | Description |
|---|
sampling_rate | number | 1.0 | The sampling rate (0.0 - 1.0). 1.0 means 100% of requests are recorded,
0.0 means 0% of requests are recorded. |
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");
});
