> ## 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.
# Tusk Drift Cloud
> Get AI-powered deviation analysis and fixes with Cloud
Use Tusk Drift's API tests in your CI/CD pipeline by running your test suite against commits in your pull requests (PRs). Our Cloud offering provides storage of these tests alongside an additional layer of intelligence on deviations detected.
Key features:
* **Automatic recording** of traces based on live traffic in your environment of choice
* **Securely store and maintain** these traces as API test suites
* **Analyze deviations** (classification of intended vs. unintended deviations), determine root cause of deviations against your code changes, and suggest fixes
## Getting Started
Haven’t set up a Tusk Drift config? Start by [following this
guide](/api-tests/installation).
Ensure you have set up the essential Tusk Drift config and verified that
recording and replaying traces work locally for your service.
Run `tusk drift init-cloud` and follow the setup wizard. It will guide you to:
1. Authorize the Tusk app for your code hosting service
2. Register your service for Tusk Drift Cloud
3. Obtain an API key to use Tusk Drift in CI/CD pipelines
To get Tusk's AI-powered deviation analysis and suggested fixes, upgrade
your account to the Business, Enterprise, or Tusk Drift plan. See [plan
details](https://usetusk.ai/pricing).
## Configuration
```yaml theme={null}
service:
id:
... (other service parameters) ...
tusk_api:
url: "https://api.usetusk.ai"
recording:
sampling:
mode: adaptive
base_rate: 0.1
min_rate: 0.001
export_spans: true
enable_env_var_recording: true
... (other config parameters) ...
```
For Tusk Drift Cloud, you’ll need to ensure these parameters are present in your `.tusk/config.yaml`:
* `service.id`: Automatically created once you complete the `tusk drift setup --skip-to-cloud` setup.
* `tusk_api.url`: Required for exporting traces and test results to Tusk.
* `recording.sampling.mode`: We generally recommend `adaptive` for deployed services so the SDK can shed recording pressure locally if exporter or runtime health degrades.
* `recording.sampling.base_rate`: The base fraction of live requests to record (a value between 0 and 1). Higher values improve fidelity but add more overhead on your service. We generally recommend setting a base rate between `0.01` and `0.1`.
* `recording.sampling.min_rate`: Optional lower bound for adaptive mode. If omitted, the SDK defaults it to `0.001`.
* `recording.sampling_rate`: Legacy alias for `recording.sampling.base_rate`. Still supported for backward compatibility.
* `recording.export_spans`: Whether to export recorded traffic to Tusk. For deployed services, set this to `true`. If set to `false` , it will export traces to your machine’s filesystem.
* `recording.enable_env_var_recording`: Whether to record and replay environment variables. We recommend setting this to `true` for accurate replay behavior if your service's logic depends on environment variables.
`TUSK_RECORDING_SAMPLING_RATE` overrides `recording.sampling.base_rate`.
See the full [configuration reference](/api-tests/configuration).
Once you obtain your Tusk API key, set this as an environment variable (`TUSK_API_KEY`) in your machine. You may also wish to add this as a GitHub secret so that GitHub Actions workflows can access it securely (see below for an example).
## Running Tusk Drift in Your CI/CD Pipeline
Once you've completed the setup above, you can integrate Tusk Drift into your CI/CD pipeline to automatically test pull requests for API regressions.
See the [CI/CD Setup Guide](/api-tests/ci-cd-setup) for complete instructions.
## Validating Suite
Tests recorded from live traffic are initially stored as **draft tests**. They are promoted to **in-suite** once validated on the default branch using `--validate-suite-if-default-branch`.
**Only seeing draft tests?** Ensure your workflow triggers on pushes to the
default branch and includes the `--validate-suite-if-default-branch` flag. See
[CI/CD Setup Guide](/api-tests/ci-cd-setup#workflow-triggers-explained) for
details.
## Deviation Analysis
When replayed against past recordings, your code change could yield **intended** deviations (this is good since existing behavior is modified as expected) or **unintended** deviations (unexpected regressions or bugs).
A Tusk Drift run in a CI/CD environment (if the `--ci` flag is present) exports test results and commit information to Tusk. For each test with a deviation, Tusk correlates the deviation with code changes and performs an analysis, classifying whether it is likely intended/unintended.
If it is unintended, Tusk will provide a **root cause analysis** and suggest fixes. A PR/MR with unintended deviations will have a “Failed” status and may be blocked from merging.
You will also see a PR/MR comment with an overview of this analysis.
If you find that Tusk’s classification is inaccurate, you can **manually override it**. This serves as feedback to improve future classifications and analyses.
If a PR/MR has deviations (whether intended or not) and is merged, the tests corresponding to these deviations will be removed from the test suite as they will no longer be valid.
## FAQs
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.
Tusk intelligently selects up to 10 unique requests for each endpoint,
prioritizing the most diverse ones to ensure comprehensive test coverage. A
maximum of 200 unique endpoints are stored for your test suite.
This is expected because Tusk will need to prune tests that don't reflect the new logic post-merge.
If you have low traffic volume, you may need to wait a few hours for Tusk to replenish tests for these APIs.
You can manually make requests to your service to trigger recordings if needed.
No. You might see a test covering that incorrect behavior in "Draft" but Tusk only promotes draft tests to
"In Suite" if the test has no deviations when run on the default branch. For context, Tusk automatically runs draft
tests on every push to the default branch.