> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usetusk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Record and Replay Tests

> Capture real-world traffic to replay as API tests in CI or CLI

<Info>
  Make sure you have followed this [installation guide](/api-tests/installation)
  to set up the Tusk Drift CLI and SDK before moving forward with this guide.
</Info>

## Record and replay your first trace

<Steps>
  <Step title="Set sampling to 100% temporarily">
    In the recording section of your `.tusk/config.yaml` file, set
    `recording.sampling.base_rate` to `1.0` while testing. For setup and
    debugging, we recommend using `recording.sampling.mode: fixed` so the SDK
    does not shed traffic under pressure. The legacy `recording.sampling_rate`
    field still works as an alias if you have not migrated yet.
  </Step>

  <Step title="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`.

    ```bash theme={null}
    TUSK_DRIFT_MODE=RECORD node server.js
    ```

    If package.json is updated with the `dev:record` script, you can run:

    ```bash theme={null}
    npm run dev:record
    ```

    <Info>
      The start command used in your `.tusk/config.yaml` should be the plain `dev` script without `TUSK_DRIFT_MODE` in it.
    </Info>

    You should then see logs indicating Tusk Drift is active. Example logs:

    ```bash theme={null}
    [TuskDrift] SDK initialized in RECORD mode
    [TuskDrift] App marked as ready
    ```
  </Step>

  <Step title="Generate traffic">
    Manually hit a simple endpoint that includes some database and/or network calls. For example:

    ```bash theme={null}
    curl http://localhost:8000/api/test/weather
    ```

    This will record a trace file, which will show up in `.tusk/traces` in your repo.
  </Step>

  <Step title="Stop recording">
    Stop the server after a few seconds with `Ctrl+C` to allow time for recorded traces to be exported.
  </Step>

  <Step title="List and replay traces">
    In your project directory, you can view the list of recorded traces by running:

    ```bash theme={null}
    tusk drift 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](/api-tests/tusk-drift-cloud), run:

    ```bash theme={null}
    tusk drift run --cloud
    ```

    The `--cloud` flag works for `tusk drift list` too.

    <Warning>When the Tusk CLI replays traces (via `tusk drift run`), it automatically sets `TUSK_DRIFT_MODE=REPLAY`. Do NOT manually set this variable in your start command in `.tusk/config.yaml`.</Warning>
  </Step>
</Steps>

## Rollout guidance

* Start recording in your dev or staging environment with
  `recording.sampling.base_rate` ≤ `0.1`; expand to production after you
  validate fidelity and coverage.
* For deployed services, consider `recording.sampling.mode: adaptive` so the
  SDK can shed recording pressure locally if exporter or runtime health
  degrades.
* 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](/api-tests/tusk-drift-cloud).
  * 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.
  ```bash theme={null}
  tusk drift run --enable-service-logs
  ```

## Troubleshooting

<AccordionGroup>
  <Accordion title="I'm not seeing any traces being recorded">
    1. Confirm that your effective base sampling rate is **not** set to `0`.
       If you're using the new nested config, check
       `recording.sampling.base_rate`. If you're still using the legacy config,
       check `recording.sampling_rate`. 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](/api-tests/pii-redaction/http-fetch-transforms).
    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.
  </Accordion>

  <Accordion title="I'm running into errors when replaying traces">
    1. Re-run the tests with service logs (logs from the SDK will also be present):
       ```bash theme={null}
       tusk drift 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:
       ```bash theme={null}
       tusk drift 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](https://github.com/Use-Tusk/drift-node-sdk?tab=readme-ov-file#requirements).
  </Accordion>

  <Accordion title="It looks like my packages aren't supported">
    If you rely on packages outside the [supported technologies or version ranges](https://github.com/Use-Tusk/drift-node-sdk?tab=readme-ov-file#requirements), reach out to [support@usetusk.ai](mailto:support@usetusk.ai) for guidance.
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="How does Drift handle PII and sensitive data?">
    You can configure
    [transforms](/api-tests/pii-redaction/http-fetch-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.
  </Accordion>

  <Accordion title="Will Drift impact my application's performance?">
    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](/api-tests/performance). If `TUSK_DRIFT_MODE`
    is set to `DISABLED` or left unset, there is zero performance impact since no
    instrumentation or recording occurs.
  </Accordion>

  <Accordion title="What happens if my API schema changes?">
    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.
  </Accordion>
</AccordionGroup>