Configuration

Environment variables, init() options and the precedence between them.

On this page

The SDK configures itself from the environment. init() exists for the cases where a value belongs in code rather than in a variable — a redaction rule, a sampling rate, an agent name your package.json cannot supply.

#Environment variables

Variable	Purpose
`TRACEHATCH_API_KEY`	Required. Selects the project and environment. Without it the SDK stays disabled and sends nothing.
`TRACEHATCH_BASE_URL`	Optional. Your API origin for a self-hosted or local Tracehatch; an `/api/v1` base works too. Defaults to the hosted API.
`TRACEHATCH_AGENT`	Optional. Agent name; defaults to the nearest `package.json` name.
`TRACEHATCH_RELEASE`	Optional. Release; defaults to `VERCEL_GIT_COMMIT_SHA`, `GITHUB_SHA` and similar, then git `HEAD`.
`TRACEHATCH_CAPTURE_BODIES`	Optional. `false` records timings, reported usage and errors without prompts, outputs or tool arguments. Defaults to `true`.

.env for Node.js · .env.local for Next.jsEnvironment

TRACEHATCH_API_KEY=your-project-api-key

Keep these in the server environment. There is no public or browser variant of the key; never ship it to a client.

#The automatic entry

The whole integrationTypeScript

import "@tracehatch/sdk/auto"

The auto entry calls init() with the environment. Use it unless you need an option below. Full loading instructions, including the preload flag and CommonJS: Manual installation.

#init()

Call init() yourself instead of the automatic entry when you want options. It replaces an earlier client and installs the capture hooks; shutdown() removes them. Unknown options are rejected rather than ignored.

A configured clientTypeScript

import { init } from "@tracehatch/sdk"

init({
  agent: "support-agent",
  captureBodies: false,
  redact: { rules: [{ name: "customer", pattern: /CUSTOMER-\d+/g }] },
  sampling: { rate: 0.25 },
})

Option	Type	Default	Notes
`apiKey`	`string`	`TRACEHATCH_API_KEY`	Prefer the variable; a key in code tends to reach source control.
`baseUrl`	`string`	Hosted API	Only for a self-hosted or local API.
`agent`	`string`	Nearest `package.json` name	Shown on runs and in the dashboard's agent breakdown.
`release`	`string`	Deployment commit	Platform variables, then git `HEAD`.
`captureBodies`	`boolean`	`true`	Wins over `TRACEHATCH_CAPTURE_BODIES` when both are set.
`redact`	`false \| RedactionOptions`	Built-ins on	`{ builtIns?, rules? }`. `false` disables masking entirely.
`sampling`	`{ rate: number }`	No sampling	Head sampling, decided per run when it starts.
`debug`	`boolean`	`false`	Logs the SDK's own diagnostics.
`flushOnExit`	`boolean`	`true`	Flush on `beforeExit`, `SIGTERM` and `SIGINT`.

init() returns a client with stats() for inspecting queued and dropped spans.

#Precedence

For every value:

An explicit init() option.
The TRACEHATCH_* process environment variable.
A value in .env.local or .env beside the running package.
The built-in default.

A key is required before anything is sent. Without one the SDK stays disabled and your application runs exactly as before.

#Redaction options

Adding to the built-insTypeScript

init({
  redact: {
    builtIns: true,
    rules: [
      { name: "customer", pattern: /CUSTOMER-\d+/g },
      { name: "internal-ticket", pattern: /TCK-[A-Z0-9]{6}/g },
    ],
  },
})

Built-ins mask email addresses, phone numbers, valid card-shaped strings, IBANs and common API key, secret and credential patterns. What is and is not covered: Privacy and data handling.

#Sampling

sampling.rate is head sampling: the decision is made per run when it starts, so spans of an unsampled run are never sent at all. This lowers cost and volume; it also means an unsampled failure is invisible, because the outcome is not known when the decision is taken.

While a workspace is over its monthly trace allowance the API answers each batch with a lower advisory rate. The SDK applies it to new runs, logs one warning, and returns to your configured rate as soon as the hint stops. See Plans, quotas and retention.

#Checking what the SDK decided

Confirm the client is liveTypeScript

import { init, flushWithResult } from "@tracehatch/sdk"

const client = init({ debug: true })
console.log(client.stats())
console.log(await flushWithResult())

flushWithResult() returns disabled when there is no initialised client — the fastest way to tell "misconfigured" apart from "nothing happened yet". See Delivery and flushing.