Make sure you have followed this installation guide to set up the Tusk Drift CLI and SDK before recording and replay your first suite of tests.

​
Record and replay your first trace

1

Set sampling to 100% temporarily

Update .tusk/config.yaml to set recording.sampling_rate to 1.0 to capture all traffic while testing.
2

Start the service in record mode

TUSK_DRIFT_MODE=RECORD node server.js
You should see logs indicating Drift is active.
[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
4

Stop recording

Stop the server after a few seconds with Ctrl+C and 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 cloud, run the following:
tusk run --cloud
The --cloud flag works for tusk list too.

​
Rollout guidance

  • Start recording in staging with sampling_rate ≤ 0.1; expand to production and increasing sampling rate after validating fidelity and coverage.
  • Keep export_spans enabled to use our cloud platform for AI-powered analysis.
  • Enable service logs when investigating issues. Logs are written under .tusk/logs/ when enabled. 
    tusk run --enable-service-logs
  • Gate production rollout behind a feature flag or environment toggle.
  • Integrate replay in CI to block regressions before merge (run tusk run in your pipeline).

​
Troubleshooting

​
1. No traces are recorded

  1. Confirm recording.sampling_rate is not 0 (set to 1.0 while testing).
  2. Verify tdSdk.markAppAsReady() is called after the server starts.
  3. Ensure the endpoint is not excluded by your configuration.

​
2. Failure to replay traces

  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 simpler endpoint (no auth or minimal dependencies) to validate setup.
  3. Confirm your dependency versions are within supported ranges listed above.

​
3. Lack of package compatibility

If you rely on packages outside the supported technologies or version ranges listed above, reach out to support@usetusk.ai for guidance.

​
FAQ

You can configure custom redaction rules for specific data patterns and provide explicit deny lists for endpoints and domains. All data is encrypted in transit and at rest, and we follow SOC 2 Type II compliance standards.
Drift is designed to have minimal performance impact—you can expect a 5% performance overhead. The SDK uses asynchronous recording and batching to avoid blocking your API responses.
Drift automatically detects schema changes and updates its understanding of your API. It will flag breaking changes as potential issues while allowing backward-compatible changes to pass through.