Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tracepilot.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The TracePilot SDK requires only an API key to get started. Beyond that, you can point the SDK at a self-hosted ingest server and take advantage of TypeScript’s type system to catch configuration mistakes at compile time. This page covers all configuration options and the recommended patterns for each.

​
API key

Your API key authenticates every request the SDK sends to the TracePilot ingest endpoint. Keys always begin with tp_live_. Retrieve yours from the TracePilot dashboard.
Never hardcode your API key directly in source code. If the key is committed to a repository — even a private one — it can be exposed through git history, forks, or accidental leaks. Store it in an environment variable and read it at runtime.
Store the key in an environment variable named TRACEPILOT_API_KEY and reference it with process.env: 
import { TracePilot } from 'tracepilot-sdk';

const tp = new TracePilot(process.env.TRACEPILOT_API_KEY!);
The ! non-null assertion tells TypeScript you have verified the variable is set. For stricter runtime validation, check the value explicitly: 
import { TracePilot } from 'tracepilot-sdk';

const apiKey = process.env.TRACEPILOT_API_KEY;
if (!apiKey) {
  throw new Error('TRACEPILOT_API_KEY environment variable is not set.');
}

const tp = new TracePilot(apiKey);
Use dotenv to load environment variables from a .env file during local development. Add .env to your .gitignore immediately. In production, use your runtime’s native secret management — for example, AWS Secrets Manager, Vercel environment variables, or Kubernetes secrets.

​
Loading with dotenv

import 'dotenv/config'; // loads .env into process.env
import { TracePilot } from 'tracepilot-sdk';

const tp = new TracePilot(process.env.TRACEPILOT_API_KEY!);
Your .env file:
.env
TRACEPILOT_API_KEY=tp_live_xxxxxxxxxxxxxxxx

​
Custom ingest endpoint

By default, the SDK sends trace data to the TracePilot cloud. If you run a self-hosted TracePilot server, pass your server’s ingest URL as the second argument to the constructor: 
import { TracePilot } from 'tracepilot-sdk';

const tp = new TracePilot(
  process.env.TRACEPILOT_API_KEY!,
  process.env.TRACEPILOT_ENDPOINT ?? 'https://your-server.com/api/ingest'
);
Store the endpoint URL in an environment variable so you can switch between environments (local, staging, production) without touching source code.

​
TypeScript setup

The SDK ships with full TypeScript types. No additional @types packages are required. Install the SDK and you’re ready: 
npm install tracepilot-sdk
For strict null checking — recommended — enable strictNullChecks in your tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true
  }
}
With strict mode enabled, TypeScript will warn you if process.env.TRACEPILOT_API_KEY could be undefined, prompting you to add the runtime check shown above.

​
Environment variable reference

VariableRequiredDescription
TRACEPILOT_API_KEYYesYour tp_live_... API key from the dashboard.
TRACEPILOT_ENDPOINTNoCustom ingest URL for self-hosted deployments.