Skip to content

nextjs-initialization.md

Latest commit

 

History

History
340 lines (274 loc) · 9.55 KB

nextjs-initialization.md

File metadata and controls

340 lines (274 loc) · 9.55 KB

Next.js Initialization (Beta)

This guide explains how to set up Tusk Drift in your Next.js application.

Step 1: Configure Next.js with withTuskDrift

Wrap your Next.js configuration with the withTuskDrift function in your next.config.js or next.config.ts file:

Basic Configuration

CommonJS (next.config.js)

// next.config.js
const { withTuskDrift } = require("@use-tusk/drift-node-sdk/next");

module.exports = withTuskDrift({
  // Your Next.js config
});

ESM (next.config.mjs)

// next.config.mjs
import { withTuskDrift } from "@use-tusk/drift-node-sdk/next";

export default withTuskDrift({
  // Your Next.js config
});

With Debug Logging for Next.js Integration

CommonJS (next.config.js)

// next.config.js
const { withTuskDrift } = require("@use-tusk/drift-node-sdk/next");

module.exports = withTuskDrift(
  {
    // Your Next.js config
  },
  {
    // Tusk Drift options
    debug: true, // Enable debug logging
  },
);

ESM (next.config.mjs)

// next.config.mjs
import { withTuskDrift } from "@use-tusk/drift-node-sdk/next";

export default withTuskDrift(
  {
    // Your Next.js config
  },
  {
    // Tusk Drift options
    debug: true, // Enable debug logging
  },
);

What withTuskDrift Does

The withTuskDrift wrapper automatically:

  • ✅ Enables the Next.js instrumentation hook (for Next.js < 15.0.0-rc.1)
  • ✅ Configures webpack externals for proper module interception
  • ✅ Detects your Next.js version and adjusts configuration accordingly
  • ✅ Preserves your existing Next.js configuration

Configuration Options

Option Type Default Description
debug boolean false Enable debug logging to see what Tusk Drift is configuring during build.
disableInstrumentationHook boolean false Disable automatic setting of experimental.instrumentationHook. Not recommended, will break Tusk Drift's Next.js integration.
suppressWarnings boolean false Suppress all warnings from Tusk Drift's Next.js integration.

Step 2: Create Instrumentation File

Create an instrumentation.ts (or .js) file at the root of your Next.js project (or inside the src folder if using one):

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { TuskDrift } = await import("@use-tusk/drift-node-sdk");

    TuskDrift.initialize({
      apiKey: process.env.TUSK_API_KEY,
      env: process.env.NODE_ENV,
      logLevel: "debug",
    });

    // Mark app as ready immediately
    TuskDrift.markAppAsReady();
  }
}

More context on setting up instrumentations for Next.js apps can be found here.

Initialization Parameters

Option Type Default Description
apiKey string Required if using Tusk Cloud Your Tusk Drift API key from the dashboard.
env string process.env.NODE_ENV The environment name (e.g., 'dev', 'staging', 'production').
logLevel 'silent' | 'error' | 'warn' | 'info' | 'debug' 'info' The logging level for the Tusk Drift SDK.
samplingRate number 1.0 Override the base sampling rate (0.0 - 1.0) for recording. Takes precedence over TUSK_RECORDING_SAMPLING_RATE and config file base-rate settings. Does not change recording.sampling.mode.

Update your package.json scripts:

{
  "scripts": {
    "dev": "next dev",
    "dev:record": "TUSK_DRIFT_MODE=RECORD next dev"
  }
}

Step 3: Configure Sampling Rate

Sampling controls what percentage of inbound requests are recorded in RECORD mode.

Tusk Drift supports two sampling modes in .tusk/config.yaml:

  • fixed: record requests at a constant base rate.
  • adaptive: start from a base rate and automatically shed load when queue pressure, export failures, export timeouts, event loop lag, or memory pressure indicate the SDK should back off. In severe conditions the SDK can temporarily pause recording entirely.

Sampling configuration is resolved in two layers:

  1. Base rate precedence (highest to lowest):
    • TuskDrift.initialize({ samplingRate: ... })
    • TUSK_RECORDING_SAMPLING_RATE
    • legacy alias TUSK_SAMPLING_RATE
    • .tusk/config.yaml recording.sampling.base_rate
    • .tusk/config.yaml legacy recording.sampling_rate
    • default base rate 1.0
  2. Mode and minimum rate:
    • recording.sampling.mode comes from .tusk/config.yaml and defaults to fixed
    • recording.sampling.min_rate is only used in adaptive mode and defaults to 0.001 when omitted

Note: Requests before TuskDrift.markAppAsReady() are always recorded. Sampling applies to normal inbound traffic after startup.

Method 1: Init Parameter

Set the base sampling rate directly in your initialization code:

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { TuskDrift } = await import("@use-tusk/drift-node-sdk");

    TuskDrift.initialize({
      apiKey: process.env.TUSK_API_KEY,
      env: process.env.NODE_ENV,
      samplingRate: 0.1, // 10% of requests
    });

    TuskDrift.markAppAsReady();
  }
}

Method 2: Environment Variable

Set the TUSK_RECORDING_SAMPLING_RATE environment variable to override the base sampling rate:

# Development - record everything
TUSK_RECORDING_SAMPLING_RATE=1.0 npm run dev

# Production - sample 10% of requests
TUSK_RECORDING_SAMPLING_RATE=0.1 npm start

TUSK_SAMPLING_RATE is still supported as a backward-compatible alias, but new setups should prefer TUSK_RECORDING_SAMPLING_RATE.

Method 3: Configuration File

Use the nested recording.sampling config to choose fixed vs adaptive mode and set the base/minimum rates.

# ... existing configuration ...

recording:
  sampling:
    mode: fixed
    base_rate: 0.1
  export_spans: true
  enable_env_var_recording: true

Adaptive sampling example:

# ... existing configuration ...

recording:
  sampling:
    mode: adaptive
    base_rate: 0.25
    min_rate: 0.01
  export_spans: true

Legacy config still supported:

recording:
  sampling_rate: 0.1

Additional Recording Configuration Options

Option Type Default Description
sampling.mode "fixed" | "adaptive" "fixed" Selects constant sampling or adaptive load shedding.
sampling.base_rate number 1.0 The base sampling rate (0.0 - 1.0). This is the preferred config key and can be overridden by TUSK_RECORDING_SAMPLING_RATE or the samplingRate init parameter.
sampling.min_rate number 0.001 in adaptive mode The minimum steady-state sampling rate for adaptive mode. In critical conditions the SDK can still temporarily pause recording.
sampling_rate number None Legacy fallback for the base sampling rate. Still supported for backward compatibility, but recording.sampling.base_rate is preferred.
export_spans boolean false Whether to export spans to the Tusk backend. If false, spans are only saved locally in .tusk/traces.
enable_env_var_recording boolean false Whether to record and replay environment variables. Recommended for accurate replay behavior if your app's logic depends on environment variables.

Troubleshooting

Instrumentation not working

If your packages aren't being instrumented:

  1. Check file location: Ensure instrumentation.ts is at the project root (same level as next.config.js), not in the app or pages directory.

  2. Check runtime guard: Make sure you have the NEXT_RUNTIME === 'nodejs' check in your register() function.

  3. Enable debug logging: Set debug: true in your withTuskDrift options to see what's being configured.