> ## 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.

# Configuration

> Complete reference for Tusk Drift configuration options

# Configuration Reference

Tusk Drift can be configured through multiple methods with the following
precedence (highest to lowest):

1. **Environment Variables**: secrets, as well as common CI settings,
2. **Initialization Parameters** via `initialize()`,
3. **YAML Configuration** in `.tusk/config.yaml`, mostly set-and-forget static
   project settings

Note that `.tusk/config.yaml` is created in your project root when you run `tusk
init`.

This document is structured as follows: the yaml configuration fields are listed
out according to their parent and their path. You can directly use these field
names in your config. This is followed by env vars and other options that are
only available as env vars or arguments.

Some settings have more specific precedence rules than the general list above.
For example, sampling-rate init params override sampling-rate environment
variables. Each section below calls out the exact override behavior where it
matters.

## `service`

Configuration related to your service identity and startup.

### `service.id`

| Type            | Required | Default | Example                                  |
| --------------- | -------- | ------- | ---------------------------------------- |
| `string` (UUID) | Yes\*    | -       | `"d7fd9519-3151-4638-b59d-8da8f6d63514"` |

\*Required when `export_spans: true`

Unique identifier for your service in Tusk Cloud. Used to associate traces with
your specific service.

### `service.name`

| Type     | Required | Default     | Example        |
| -------- | -------- | ----------- | -------------- |
| `string` | No       | `"unknown"` | `"my-service"` |

Human-readable service name displayed in Tusk Cloud dashboard and CLI output.

### `service.port`

| Type     | Required | Default | Example |
| -------- | -------- | ------- | ------- |
| `number` | No       | -       | `8080`  |

Port number your service runs on, used by CLI for health checks.

### `service.start.command`

| Type     | Required | Default | Example       |
| -------- | -------- | ------- | ------------- |
| `string` | No       | -       | `"npm start"` |

Command executed by `tusk run` to start your service. Should **NOT** include
`TUSK_DRIFT_MODE` environment variable.

### `service.readiness_check`

Configuration for verifying service is ready to accept requests.

#### `service.readiness_check.command`

| Type     | Required | Default | Example                                  |
| -------- | -------- | ------- | ---------------------------------------- |
| `string` | No       | -       | `"curl -f http://localhost:8080/health"` |

Command to check if service is ready (e.g., curl health endpoint).
Note that your code should have called `mark_app_as_ready` before this
endpoint's first successful response.

#### `service.readiness_check.timeout`

| Type     | Required | Default | Example |
| -------- | -------- | ------- | ------- |
| `string` | No       | `"45s"` | `"30s"` |

Maximum time to wait for readiness check to succeed.

#### `service.readiness_check.interval`

| Type     | Required | Default | Example |
| -------- | -------- | ------- | ------- |
| `string` | No       | `"5s"`  | `"2s"`  |

Time between readiness check attempts.

## Sampling

Tusk Drift supports both fixed sampling and adaptive sampling. In adaptive mode,
the SDK starts from a configured base rate and can temporarily reduce recording
under local pressure such as exporter backlog or runtime memory pressure.

### `recording.sampling.mode`

| Type     | Required | Default   | Example      |
| -------- | -------- | --------- | ------------ |
| `string` | No       | `"fixed"` | `"adaptive"` |

Selects the sampling strategy for recording live traffic. Supported values are
`fixed` and `adaptive`.

### `recording.sampling.base_rate`

| Type               | Required | Default | Example |
| ------------------ | -------- | ------- | ------- |
| `number` (0.0-1.0) | No       | `1.0`   | `0.1`   |

Base fraction of live requests to record during trace collection. In `fixed`
mode this is the effective rate. In `adaptive` mode the SDK may temporarily
reduce below this base rate under pressure.

* Can be set via environment variable: `TUSK_RECORDING_SAMPLING_RATE`
* Legacy environment variable alias: `TUSK_SAMPLING_RATE`
* Can be set via initialization parameter: `samplingRate`

### `recording.sampling.min_rate`

| Type               | Required | Default                                     | Example |
| ------------------ | -------- | ------------------------------------------- | ------- |
| `number` (0.0-1.0) | No       | `0.001` in `adaptive` mode, unset otherwise | `0.01`  |

Lower bound for adaptive sampling after load shedding is applied. This is only
used in `adaptive` mode.

### `recording.sampling.log_transitions`

| Type      | Required | Default | Example |
| --------- | -------- | ------- | ------- |
| `boolean` | No       | `true`  | `false` |

Whether the SDK should emit adaptive-sampling transition logs such as
`Adaptive sampling updated (...)`. Only relevant in `adaptive` mode.

* Can be set via environment variable: `TUSK_RECORDING_SAMPLING_LOG_TRANSITIONS`

### `recording.sampling_rate`

| Type               | Required | Default | Example |
| ------------------ | -------- | ------- | ------- |
| `number` (0.0-1.0) | No       | -       | `0.5`   |

Deprecated legacy alias for `recording.sampling.base_rate`. Still supported for
backward compatibility.

## `traces`

### `traces.dir`

| Type     | Required | Default          | Example          |
| -------- | -------- | ---------------- | ---------------- |
| `string` | No       | `".tusk/traces"` | `".tusk/traces"` |

Directory where local trace files are stored when not exporting to Tusk Cloud.

## `recording`

### `recording.export_spans`

| Type      | Required | Default | Example |
| --------- | -------- | ------- | ------- |
| `boolean` | No       | `false` | `true`  |

Whether to export spans to Tusk Cloud backend. If `false`, spans are stored
locally only.

## `test_execution`

### `test_execution.concurrency`

| Type     | Required | Default | Example |
| -------- | -------- | ------- | ------- |
| `number` | No       | `10`    | `5`     |

Maximum number of concurrent test executions.

### `test_execution.timeout`

| Type     | Required | Default | Example |
| -------- | -------- | ------- | ------- |
| `string` | No       | `"30s"` | `"60s"` |

Timeout for individual test executions.

## `comparison`

### `comparison.ignore_fields`

| Type       | Required | Default | Example                      |
| ---------- | -------- | ------- | ---------------------------- |
| `string[]` | No       | -       | `["timestamp", "requestId"]` |

List of field names to ignore during trace comparisons (e.g., timestamps, random IDs).

## `recording`

### `recording.enable_env_var_recording`

| Type      | Required | Default | Example |
| --------- | -------- | ------- | ------- |
| `boolean` | No       | `false` | `true`  |

Whether to record and replay environment variables. Recommended if your application logic depends on environment variables.

### `recording.enable_analytics`

| Type      | Required | Default | Example |
| --------- | -------- | ------- | ------- |
| `boolean` | No       | `false` | `true`  |

Whether to enable anonymous usage analytics collection.

### `recording.exclude_paths`

| Type       | Required | Default | Example                   |
| ---------- | -------- | ------- | ------------------------- |
| `string[]` | No       | -       | `["/health", "/metrics"]` |

List of URL paths to exclude from recording (e.g., health checks, metrics endpoints).

## `tusk_api`

### `tusk_api.url`

| Type           | Required | Default        | Example                   |
| -------------- | -------- | -------------- | ------------------------- |
| `string` (URL) | No       | Tusk cloud URL | `"http://localhost:8000"` |

Base URL for Tusk Cloud API endpoints. Can be changed for local development or
custom/on-prem deployments. If you are using Tusk Cloud, there is very little
need to set this.

* Can be set via environment variable: `TUSK_API_URL`

### `tusk_api.auth0_domain`

| Type     | Required | Default              | Example                |
| -------- | -------- | -------------------- | ---------------------- |
| `string` | No       | Tusk cloud Auth0 URL | `"tusk.dev.auth0.com"` |

Auth0 domain used for CLI authentication. Only needed for custom/on-prem deployments.

* Can be set via environment variable: `TUSK_AUTH0_DOMAIN`

### `tusk_api.auth0_client_id`

| Type     | Required | Default              | Example                              |
| -------- | -------- | -------------------- | ------------------------------------ |
| `string` | No       | Tusk cloud client id | `"TxwUtpScbKam4xGWcGEEMLpwlpeECJS5"` |

Auth0 client ID used for CLI authentication. Only needed for custom/on-prem
deployments.

* Can be set via environment variable: `TUSK_AUTH0_CLIENT_ID`

## CLI Communication (Replay Mode)

### TUSK\_MOCK\_SOCKET (Unix Socket)

| Type     | Required | Default                  | Example                  |
| -------- | -------- | ------------------------ | ------------------------ |
| `string` | No       | `/tmp/tusk-connect.sock` | `/tmp/tusk-connect.sock` |

Unix socket path for CLI communication in local development. Automatically
managed by Tusk CLI.

* Can be set via environment variable: `TUSK_MOCK_SOCKET`

### TUSK\_MOCK\_HOST / TUSK\_MOCK\_PORT (TCP)

| Type               | Required | Default | Example |
| ------------------ | -------- | ------- | ------- |
| `string`, `string` | No       | -       | -       |

TCP connection details for CLI communication in Docker environments.
Automatically set by Tusk CLI in containerized environments.

* Can be set via environment variables: `TUSK_MOCK_HOST`, `TUSK_MOCK_PORT`

## Operation Mode

| Type     | Required | Default      | Example    |
| -------- | -------- | ------------ | ---------- |
| `string` | No       | `"DISABLED"` | `"RECORD"` |

Controls how the SDK operates in your application.

* Can be set via environment variable: `TUSK_DRIFT_MODE`

**Valid values:**

* `"RECORD"`: Records traces for all instrumented operations (use in
  staging/production)
* `"REPLAY"`: Replays previously recorded traces (automatically set by `tusk
  run`, do **NOT** set manually!). This will disable instrumented packages'
  egress traffic.
* `"DISABLED"`: Disables all instrumentation

## API Key

| Type     | Required | Default | Example                 |
| -------- | -------- | ------- | ----------------------- |
| `string` | Yes\*    | -       | `"td_1234567890abcdef"` |

\*Required when `export_spans: true`

Your Tusk Drift API key for authenticating with Tusk Cloud services. **Note:**
This is a confidential value and should only be provided via environment
variable or initialization parameter, not in YAML configuration.

* Can be set via initialization parameter: `apiKey`

## Environment

| Type     | Required | Default         | Example        |
| -------- | -------- | --------------- | -------------- |
| `string` | No       | `"development"` | `"production"` |

Environment name used for organizing traces (e.g., "development", "staging",
"production").

* If not provided, `NODE_ENV` is used as default
* Can be set via initialization parameter: `env`

## Logging

| Type     | Required | Default  | Example   |
| -------- | -------- | -------- | --------- |
| `string` | No       | `'info'` | `'debug'` |

Controls the verbosity of SDK logging.

* Can be set via initialization parameter: `logLevel`

**Valid values:** `'silent'`, `'error'`, `'warn'`, `'info'`, `'debug'`

## Transforms Configuration

### `transforms`

| Type               | Required | Default | Example |
| ------------------ | -------- | ------- | ------- |
| `TransformConfigs` | No       | -       | -       |

PII redaction and data transformation rules for HTTP and Fetch requests.

* Can be set via initialization parameter: `transforms`

For detailed information about transforms syntax and examples, see the [PII Redaction documentation](/api-tests/pii-redaction/basic-concepts).

## Complete Configuration Example

```yaml .tusk/config.yaml theme={null}
service:
  id: "d7fd9519-3151-4638-b59d-8da8f6d63514"
  name: "my-backend-service"
  port: 8080
  start:
    command: "npm start"
  readiness_check:
    command: "curl -f http://localhost:8080/health"
    timeout: "30s"
    interval: "2s"

traces:
  dir: ".tusk/traces"

tusk_api:
  url: "https://api.usetusk.ai"
  auth0_domain: "tusk.us.auth0.com"
  auth0_client_id: "gXktT8e38sBmmXGWCGeXMLpwlpeECJS5"

test_execution:
  concurrency: 5
  timeout: "60s"

comparison:
  ignore_fields: ["timestamp", "requestId"]

recording:
  sampling:
    mode: adaptive
    base_rate: 0.5
    min_rate: 0.01
  export_spans: true
  enable_env_var_recording: true
  enable_analytics: false
  exclude_paths: ["/health", "/metrics"]

transforms:
  http:
    - matcher:
        direction: "inbound"
        method: ["POST"]
        pathPattern: "/api/auth/*"
        jsonPath: "$.password"
      action:
        type: "redact"

    - matcher:
        direction: "outbound"
        host: "api.stripe.com"
        headerName: "Authorization"
      action:
        type: "replace"
        replaceWith: "Bearer test-token-12345"

    - matcher:
        direction: "inbound"
        pathPattern: "/admin/internal/*"
      action:
        type: "drop"
```

## Initialization Example

```typescript theme={null}
import { TuskDrift } from "@use-tusk/drift-node-sdk";

TuskDrift.initialize({
  apiKey: process.env.TUSK_API_KEY,
  env: process.env.NODE_ENV || "development",
  logLevel: "info",
  samplingRate: 0.1,
  transforms: {
    http: [
      {
        matcher: {
          direction: "inbound",
          pathPattern: "/api/*",
          jsonPath: "$.ssn",
        },
        action: {
          type: "mask",
          maskChar: "X",
        },
      },
    ],
  },
});
```