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(),
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.

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

`recording.sampling_rate`

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

Percentage of requests to record during trace collection. 1.0 = 100%, 0.1 = 10%, etc.

Can be set via environment variable: TUSK_SAMPLING_RATE
Can be set via initialization parameter: samplingRate

`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	`"https://api.usetusk.ai"`	`"http://localhost:8000"`

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

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 pacakges’ 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"

test_execution:
  concurrency: 5
  timeout: "60s"

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

recording:
  sampling_rate: 0.5
  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",
        },
      },
    ],
  },
});

Get Started

Platform

Best Practices

Analytics API

​Configuration Reference

​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 Rate

​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

​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

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

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

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