Configuration Reference

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

Environment Variables: secrets, as well as common CI settings,
Initialization Parameters via initialize(),
Config override file via --config-override flag or TUSK_CONFIG_OVERRIDE env var,
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.

Config Overrides

You can provide a config override file that is merged on top of the base config. Only the fields you specify in the override file are changed; everything else is preserved from the base config. This is useful for local-only settings like disabling span export or changing the sampling mode without modifying the shared config file. Using the --config-override flag:

tusk drift run --config-override .tusk/local-config.yaml
tusk drift list --config-override .tusk/local-config.yaml

Using the TUSK_CONFIG_OVERRIDE env var:

TUSK_CONFIG_OVERRIDE=.tusk/local-config.yaml tusk drift run

The --config-override flag takes precedence over the TUSK_CONFIG_OVERRIDE env var. Both are overridden by individual environment variables. Example override file:

.tusk/local-config.yaml

recording:
  sampling:
    mode: fixed
    base_rate: 1.0
  export_spans: false
  enable_env_var_recording: false

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

Can be set via environment variable: TUSK_RECORDING_SAMPLING_MODE

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

Can be set via environment variable: TUSK_RECORDING_EXPORT_SPANS

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

Can be set via environment variable: TUSK_ENABLE_ENV_VAR_RECORDING

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

Complete Configuration Example

.tusk/config.yaml

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

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",
        },
      },
    ],
  },
});

​Configuration Reference

​Config Overrides

​service

​service.id

​service.name

​service.port

​service.start.command

​service.readiness_check

​service.readiness_check.command

​service.readiness_check.timeout

​service.readiness_check.interval

​Sampling

​recording.sampling.mode

​recording.sampling.base_rate

​recording.sampling.min_rate

​recording.sampling.log_transitions

​recording.sampling_rate

​traces

​traces.dir

​recording

​recording.export_spans

​test_execution

​test_execution.concurrency

​test_execution.timeout

​comparison

​comparison.ignore_fields

​recording

​recording.enable_env_var_recording

​recording.enable_analytics

​recording.exclude_paths

​tusk_api

​tusk_api.url

​tusk_api.auth0_domain

​tusk_api.auth0_client_id

​CLI Communication (Replay Mode)

​TUSK_MOCK_SOCKET (Unix Socket)

​TUSK_MOCK_HOST / TUSK_MOCK_PORT (TCP)

​Operation Mode

​API Key

​Environment

​Logging

​Transforms Configuration

​transforms

​Complete Configuration Example

​Initialization Example

Configuration Reference

Config Overrides

`service`

`service.id`

`service.name`

`service.port`

`service.start.command`

`service.readiness_check`

`service.readiness_check.command`

`service.readiness_check.timeout`

`service.readiness_check.interval`

Sampling

`recording.sampling.mode`

`recording.sampling.base_rate`

`recording.sampling.min_rate`

`recording.sampling.log_transitions`

`recording.sampling_rate`

`traces`

`traces.dir`

`recording`

`recording.export_spans`

`test_execution`

`test_execution.concurrency`

`test_execution.timeout`

`comparison`

`comparison.ignore_fields`

`recording`

`recording.enable_env_var_recording`

`recording.enable_analytics`

`recording.exclude_paths`

`tusk_api`

`tusk_api.url`

`tusk_api.auth0_domain`

`tusk_api.auth0_client_id`

CLI Communication (Replay Mode)

TUSK_MOCK_SOCKET (Unix Socket)

TUSK_MOCK_HOST / TUSK_MOCK_PORT (TCP)

Operation Mode

API Key

Environment

Logging

Transforms Configuration

`transforms`

Complete Configuration Example

Initialization Example