Quickstart

01Connect your app with the guided installer

Open your Tracehatch project and copy the recommended setup command. Run it from your existing application directory. The installer detects your framework and package manager, opens your browser to connect the project, and previews the files it will change before applying them.

• Install in the server package that actually makes model calls. In a monorepo, confirm the detected application. Next.js uses server instrumentation; Node.js and NestJS / Express load the SDK before the application starts.
• Confirm the project and development environment in your signed-in browser. The installer receives a project ingestion key and saves it privately; you do not need to paste it into chat or a command.
• Choose whether to capture prompts and responses. Guided setup starts with body capture disabled and preserves your existing provider credentials, model and requests.
• Review and apply the changes. Restart your app, use one existing AI feature, and return to setup to inspect the resulting model call. A connection-check trace alone does not mean your app is recording.

The installer requires Node.js 22+ and is downloaded from your Tracehatch app. It installs the versioned SDK archive as @tracehatch/sdk. Python and other servers use the gateway or log endpoint through manual/AI-assisted setup. Native Python, browser/Edge SDKs and an OTLP receiver are not available yet.

02Manual setup: choose a project

• Create a free account — a workspace and a sample project are created with it.
• Explore the sample project, then create your own project to record runs. Sample projects do not accept API keys.
• Create or choose a key in project setup. You can also manage keys in Project settings → API keys. A new secret is shown once; save it then.
• A key selects both the project and the environment, so use a development key while you experiment.

TRACEHATCH_API_KEY=<your-api-key>

Save the key beside the server application's package.json, and ensure the environment file is ignored by Git. Next.js loads .env.local automatically. The Node.js commands below load .env explicitly with --env-file, which requires Node.js 20.6+. Restart your app after changing configuration.

Hosted Tracehatch needs no API URL setting. Only self-hosted or local Tracehatch installations need TRACEHATCH_BASE_URL set to their API origin. A key selects both project and environment. Development traffic does not count against your allowance; staging and custom environments do.

03Install the SDK

Install @tracehatch/sdk@0.2.1 from the archive below in the server package that makes your model calls. The SDK runs on Node.js 18+ and supports ESM and CommonJS with no runtime dependencies. A local Tracehatch checkout is not required.

npm install https://tracehatch.com/downloads/tracehatch-sdk-0.2.1.tgz

Project setup includes npm, pnpm, Yarn and Bun install commands. Use your existing package manager and commit the updated lockfile. Bun runtime compatibility is unverified. Python and other languages need no package: they use the gateway or the log endpoint.

04Record your app’s model calls

Choose the Node.js or Next.js instructions below. Both initialize Tracehatch with prompt and response capture disabled. Keep your existing provider credentials, model and requests. Once connected, restart your app and trigger one of its existing AI actions.

import { init } from "@tracehatch/sdk"

init({ captureBodies: false })

node --env-file=.env --import ./tracehatch.setup.mjs server.js

Replace server.js with the entry file your app already runs and preserve its existing arguments. The separate preload runs before imported model clients are created; placing init() in the entry-file body can be too late. For NestJS, Express, TypeScript runners or custom start scripts, choose your stack in project setup to adapt this bootstrap. Node.js 18.18–20.5 users can set the private variables in their terminal and omit --env-file; earlier Node.js 18 needs an adapted bootstrap.

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { init } = await import("@tracehatch/sdk")
    init({ captureBodies: false })
  }
}

For Next.js, merge this code into an existing register() function if you have one. Keep the key in .env.local and use the Node.js runtime for AI routes. Restart with your existing development command. Do not add the Node preload command to Next.js; instrumentation.ts handles startup. In short-lived route handlers, use after(() => flush()) so export finishes after the response.

These examples intentionally use init({ captureBodies: false }). Change that option to true only when you want prompts and responses recorded. Do not also load the automatic /auto entry, which uses the SDK’s body-capture default.

• OpenAI: Captured automatically: chat.completions, responses and embeddings, including streams and background responses. Keep your existing client and model.
• Anthropic: Captured automatically: messages.create and messages.stream. Keep your existing client and Claude model.
• OpenAI-compatible endpoint: Captured automatically for OpenAI-compatible hosts such as Azure OpenAI, Groq, Mistral, Together, OpenRouter, DeepSeek, xAI and Ollama. Provider-specific pricing is not guaranteed.
• Gemini / other providers or frameworks: Frameworks that call a supported API shape through fetch are captured automatically. Other providers use a manual generation span around the real call, or the log endpoint from any language.

Automatic capture is available in the Node SDK and through the gateway. Support follows API methods and response shapes, not a fixed model list. Capturing a new or custom model does not guarantee price coverage. Other backends point their OpenAI or Anthropic client at the gateway, or send one JSON object per model call to the log endpoint.

• Model calls capture model/provider, reported token usage, first-token timing, finish reasons and provider errors. Runs are created per inbound request or per agent loop; tool calls and their results become tool spans. Bodies are omitted while captureBodies is false.
• tool(name, fn, { retries: 2 }) makes up to three attempts inside one span, recording attempt timing and errors. Supply tool input explicitly; the callback return value becomes the final output.
• Sessions and users come from the x-tracehatch-session-id and x-tracehatch-user-id request headers, OpenAI conversations, the user field, or a fingerprint of the system prompt and first user message; setSession() and setUser() override them.
• Streams are read from a copy while your code consumes the response. Inside an explicit trace(), keep the callback open until the stream is consumed or cancelled. OpenAI chat streams get stream_options.include_usage added unless you set it.

05Optional: check delivery without a model request

If you want to check the key and connection first, save this script beside package.json. It sends a diagnostic trace without a model key, paid request or prompt capture. It does not instrument your application, and a successful delivery does not finish application setup.

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

if (!process.env.TRACEHATCH_API_KEY?.trim()) {
  throw new Error("Set TRACEHATCH_API_KEY in this terminal first")
}
init({ captureBodies: false, flushOnExit: false })
try {
  const traceId = await trace("Tracehatch connection check", (run) => run.id)
  const result = await flushWithResult()
  if (result.status !== "accepted") {
    console.error("Delivery failed:", result)
    process.exitCode = 1
  } else {
    console.log("Batch accepted. Open trace", traceId, "in Tracehatch.")
  }
} finally {
  await shutdown()
}

node --env-file=.env tracehatch-check.mjs

node --env-file=.env.local tracehatch-check.mjs

The standalone check does not inherit Next.js environment loading, so keep --env-file=.env.local in its command. On Node.js 18, set the private variables in the same terminal first, then run node tracehatch-check.mjs without --env-file. Project setup includes macOS/Linux and PowerShell environment commands.

flushWithResult() distinguishes HTTP acceptance from failed or disabled delivery. Return to setup to confirm the diagnostic trace was processed. Then run a real AI action in your application and inspect its model-call trace.

06Read the run

A diagnostic trace proves delivery; a model call from your application confirms capture. Trigger an existing AI action, open the exact recorded trace and confirm it is the action you just performed. The timeline shows what called what; a model step shows duration, reported tokens, errors and cost when pricing is available. From Traces:

• Traces — the waterfall, span details, prompts and outputs, logs, metadata and the timeline. A failed run opens on the span that broke.
• Sessions — filter by end user or failures, read retained conversation turns, and follow each turn into its trace.
• Costs — recorded spend, average per run, tokens, the spend chart and the most expensive runs.
• Models — compare model/provider calls, reported tokens, cost, failures, latency and first-token timing where available.
• Tools — compare call volume, failures, attempt counts and latency; inspect recent errors in their exact trace steps.
• Spans — search individual steps by kind, status, model, provider, tool or duration, inspect latency distributions and open matching traces.
• Dashboard — requests, failure rate, latency and spend for the selected range and environment, compared with the period before it.

The free plan shows the dashboard, traces, sessions and cost totals. Breakdowns and the Models, Tools and Spans pages are Pro capabilities.

Aggregate queries cover up to 90 days. The Spans explorer, recent model/tool calls and expensive-run lists cover the latest 24 hours within the selected range, subject to trace retention. Captured bodies may be redacted, truncated or unavailable.

07What leaves your process

• The installer and this manual quickstart start with body capture disabled. Prompts and responses are an explicit choice. The SDK's automatic import uses its default of body capture on. Redaction runs in the SDK first and masks common personal-data and secret patterns, but can miss values.
• init({ captureBodies: false }) omits span inputs and outputs; timings and reported usage are still recorded. Review custom attributes and logs separately, and do not rely on pattern matching to remove every secret.
• Spans are batched and exported over HTTP in the background. flush() waits for pending export with a bounded timeout; flushWithResult() reports delivery status. shutdown() flushes and stops the exporter, so reserve it for process shutdown rather than each server request.
• Trace retention follows your plan: 7 days on Free, 90 days on Pro, no plan-based trace expiry on Enterprise. Expired runs are deleted nightly while aggregates and usage counters remain. Raw ingest payloads expire separately after 24 hours on every plan.
• Above the free allowance, sampling applies. Failed traces received by the server are kept until the hard stop, but SDK head sampling can omit whole runs before their outcome is known. At three times the allowance, batches from all project keys are rejected until the UTC month resets.

08Connect your deployed application

• Once local capture works, create an ingestion key for the production environment in the same project.
• Add TRACEHATCH_API_KEY to your hosting provider's private server environment settings. Set TRACEHATCH_BASE_URL only for a self-hosted API. Never use a public client variable for a key.
• Commit the reviewed SDK initialization and package lockfile, deploy, then trigger an AI action on the deployed app. Local environment files are not uploaded by the installer.
• Select Production in Tracehatch and inspect the new run. For short-lived Node processes and AWS Lambda, await flush() before returning; Vercel functions hand the final flush to waitUntil.

If no model call arrives, check that the SDK initializes before provider clients, that the actual server has its key, and that your request uses a supported API shape through global fetch. The installer’s doctor command checks delivery; the app's real trace confirms capture.

09Preview availability

Tracehatch is in preview. Available capabilities include ingestion, tracing, sessions, dashboard, cost, model, tool and span analytics, usage metering and retention.

The Node SDK is distributed as a versioned archive from this site and imported as @tracehatch/sdk. Pro and Enterprise analytics depend on the workspace’s configured plan; plan changes and payments are not available in the app.