Deploy to production

Create a production key, configure your host, and flush before short-lived processes return.

On this page

Local setup does not configure production. Environment files are never uploaded by the installer, and a development key would send production traffic to the wrong environment.

Create a production key

In the same project, create an ingest key for the production environment. Production keys start with th_live_; every other environment gets th_test_.

Rotate without downtime by creating the new key before revoking the old one. Both work until you revoke.

Add it to your host's private server environment

Set TRACEHATCH_API_KEY in your hosting provider's server environment settings. Only a self-hosted or local Tracehatch API also needs TRACEHATCH_BASE_URL; the hosted API is the SDK's default.

Commit the reviewed integration

Commit the initialization the installer wrote (the preload flag, the instrumentation file or the first import), the package manifest and the lockfile. Make sure any custom production start script loads the same initialization — a start:prod that bypasses the edited start script will record nothing.

Deploy, then trigger a real AI action

Select Production in Tracehatch and open the new run. As locally, the run from your own application is the evidence, not a connection check.

#Flush before the process ends

Spans are batched and exported in the background. A long-lived server flushes on its own; a process that can be frozen or killed the moment it returns a response needs to be told to wait.

Host	What to do
Long-running Node server	Nothing. The queue flushes on `beforeExit`, `SIGTERM` and `SIGINT`.
Vercel functions	Nothing. The final flush is handed to `waitUntil`.
AWS Lambda, Netlify and similar	`await flush()` before the handler returns.
Next.js route handlers	`after(() => flush())` so export finishes after the response.
Scripts, queues, cron jobs	`await flush()` before exit, or `await shutdown()` at the very end.

A Lambda-style handlerTypeScript

import { flush } from "@tracehatch/sdk"

export async function handler(event) {
  try {
    return await answer(event)
  } finally {
    await flush()
  }
}

flush() never rejects and waits up to five seconds by default. Reserve shutdown() for actual process shutdown: it flushes, stops timers and removes the capture hooks, so calling it per request would stop recording.

Details, statuses and the queue's limits: Delivery and flushing.

#Environments and metering

A key selects both the project and the environment. The environment you filter by in the app is the one the key wrote to.
Development traffic does not count against your monthly trace allowance. Staging, production and any custom environment do.
Sample projects are excluded from metering and from your project limit.

See Plans, quotas and retention for what happens above the allowance.

#Name your releases

The run's release defaults to the deployment's commit: VERCEL_GIT_COMMIT_SHA, GITHUB_SHA and similar platform variables, then git HEAD. Set TRACEHATCH_RELEASE to override it, and TRACEHATCH_AGENT to name the agent when the nearest package.json name is not what you want to see on runs.

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

TRACEHATCH_API_KEY=your-project-api-key