@trakr/monitor

Observability for AI agent workflows. Automatically captures Anthropic and OpenAI calls — cost, tokens, latency, and tool use — and sends them to your Trakr dashboard.

Requirements

• Node.js 18+
• A Trakr API key (tk_live_... from Settings → API Keys)
• Optional: @anthropic-ai/sdk and/or openai in your app (not bundled; install only what you use)

Install

npm install @trakr/monitor
# or
pnpm add @trakr/monitor
# or
yarn add @trakr/monitor

Provider SDKs for auto-instrumentation (install in your app):

npm install @anthropic-ai/sdk   # Anthropic
npm install openai              # OpenAI

Quick start

Call init() once before any LLM calls:

import Trakr from '@trakr/monitor';

Trakr.init({ apiKey: process.env.TRAKR_API_KEY });

// Anthropic / OpenAI calls are traced automatically

Or rely on the environment variable:

Trakr.init(); // reads TRAKR_API_KEY

ESM apps: If you import Anthropic or OpenAI, use await Trakr.initAsync() so patches apply to the same module graph:

await Trakr.initAsync({ apiKey: process.env.TRAKR_API_KEY });

Automatic instrumentation

After init, existing client usage stays the same:

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello' }],
});

No wrappers or callbacks required. The SDK never throws on ingest failures and does not block your request path (events batch asynchronously).

Manual workflow runs

Group multi-step work under a named run in the dashboard:

const run = Trakr.startRun('invoice-extractor', {
  metadata: { invoice_id: 'INV-001' },
});

try {
  const result = await extractInvoice(document);
  await run.end({ status: 'success' });
  return result;
} catch (error) {
  await run.end({
    status: 'error',
    errorMessage: error instanceof Error ? error.message : String(error),
  });
  throw error;
}

Scripts and serverless

Long-running servers flush on a timer. For short-lived processes, flush before exit:

await Trakr.flush();

Configuration

| Option | Default | Description | |--------|---------|-------------| | apiKey | TRAKR_API_KEY env | SDK API key (tk_live_...) | | endpoint | https://app.trakr.run/api/ingest | Ingest URL override | | batchSize | 10 | Events per upload batch | | flushIntervalMs | 2000 | Max time between uploads | | loopDetectionThreshold | 5 | Consecutive identical tool calls before loop_detected | | disabled | false | Disable all instrumentation | | debug | false | Log SDK activity to console |

API

Trakr.init(options?: TrakrInitOptions): void;
Trakr.initAsync(options?: TrakrInitOptions): Promise<void>;
Trakr.startRun(workflowName: string, options?): Run;
Trakr.flush(): Promise<void>;
Trakr.disable(): void;
Trakr.version: string;

run.end({ status: 'success' | 'error', errorMessage?: string }): Promise<void>;
run.setMetadata(key, value): void;

Documentation

• Getting started
• TypeScript SDK
• Ingest API

Support

Questions or issues: [email protected]

License

MIT