Skip to main content
Make sure you have followed this installation guide to set up the Tusk Drift CLI and SDK before moving forward with this guide.

​
Record and replay your first trace

1

Set sampling to 100% temporarily

In the recording section of your .tusk/config.yaml file, set sampling_rate to 1.0 to capture all traffic while testing.
2

Start the service in record mode

Start your service in your dev or staging environment while enabling auto-recording of traces with TUSK DRIFT_MODE=RECORD.
TUSK_DRIFT_MODE=RECORD node server.js
If package.json is updated with the dev:record script, you can run:
npm run dev:record
The start command used in your .tusk/config.yaml should be the plain dev script without TUSK_DRIFT_MODE in it.
You should then see logs indicating Tusk Drift is active. Example logs:
[TuskDrift] SDK initialized in RECORD mode
[TuskDrift] App marked as ready
3

Generate traffic

Manually hit a simple endpoint that includes some database and/or network calls. For example:
curl http://localhost:8000/api/test/weather
This will record a trace file, which will show up in .tusk/traces in your repo.
4

Stop recording

Stop the server after a few seconds with Ctrl+C to allow time for recorded traces to be exported.
5

List and replay traces

In your project directory, you can view the list of recorded traces by running:
tusk list
You can select which ones to replay as tests locally. Successful replay confirms deterministic behavior with outbound calls mocked from recordings.If you’d like to replay all traces and export the traces to Tusk Drift Cloud, run:
tusk run --cloud
The --cloud flag works for tusk list too.
When the Tusk CLI replays traces (via tusk run), it automatically sets TUSK_DRIFT_MODE=REPLAY. Do NOT manually set this variable in your start command in .tusk/config.yaml.

​
Rollout guidance

  • Start recording in your dev or staging environment with sampling_rate ≤ 0.1; expand to production and increase sampling rate after you validate fidelity and coverage.
    • Gate production rollout of Tusk Drift behind a feature flag or environment toggle.
  • Customize the Tusk config file (.tusk/config.yaml) to suit your needs
    • Set export_spans: true to use our Cloud platform for AI-powered root cause analysis and suggested fixes. This allows you to integrate replay in CI to block regressions before merge. Read more.
    • Set enable_env_var_recording: true if your app’s business logic depends on environment variables; this reduces the occurrence of noisy deviations in actual vs. expected output.
  • Enable service logs when investigating issues. Logs are written under .tusk/logs/ when enabled. 
    tusk run --enable-service-logs

​
Troubleshooting

  1. Confirm that the sampling_rate in your .tusk/config.yaml is not set to 0 (set it to 1.0 while testing).
  2. Verify TuskDrift.markAppAsReady() is called after the server starts.
  3. Ensure the endpoint is not excluded by your PII redaction rules.
  4. Confirm that you’re setting TUSK_DRIFT_MODE=RECORD when starting your service. If TUSK_DRIFT_MODE is unset or set to DISABLED, Tusk Drift won’t record any data.
  5. The trace you’re trying to record may be larger than 1 MB. Consider setting enable_env_var_recording: false in your Tusk config file if your application’s business logic does not depend on environment variables.
  1. Re-run the tests with service logs (logs from the SDK will also be present): 
    tusk run --enable-service-logs
    Read the log file in .tusk/logs to investigate the error. Optionally, to get the full debug logs including the service logs, run: 
    tusk run --debug
  2. Start with a simple endpoint (no auth or minimal dependencies) to validate your setup.
  3. Confirm your dependency versions are within supported ranges listed here.
If you rely on packages outside the supported technologies or version ranges, reach out to support@usetusk.ai for guidance.

​
FAQ

You can configure transforms for specific data patterns to redact, mask, replace, or drop sensitive data. All data is encrypted in transit and at rest, and we follow SOC 2 Type II compliance standards.
Expect a 1-2% throughput overhead. Transforms result in a 1.0% increase in tail latency when a small number of transforms are registered; its impact scales linearly with the number of transforms registered. For more details, see our performance benchmarks.If TUSK_DRIFT_MODE is set to DISABLED or left unset, there is zero performance impact since no instrumentation or recording occurs.
Drift detects schema changes and––with the Cloud platform––uses its understanding of your PR’s code and business context to flag breaking changes as issues while allowing intended changes to pass through.