@spect-tools/track

The tracking library for spect.tools. Currently in alpha.

Supporting:

• Vercel AI SDK as middleware and telemetry integration
• Claude Agent SDK

See https://docs.spect.tools/quickstart to use Spect in your application.

Installation

npm install @spect-tools/track
# or
pnpm add @spect-tools/track
# or
yarn add @spect-tools/track

Peer Dependencies

# For Vercel AI SDK (wrap middleware or telemetry)
npm install ai

# For Claude Agent SDK
npm install @anthropic-ai/claude-agent-sdk

Usage

Vercel AI SDK

Wrap your language model to enable automatic trace collection. Requires ai@^6 or ai@^7:

import { wrap } from '@spect-tools/track/ai-sdk-middleware';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const wrappedModel = wrap(openai('gpt-4o'), {
  organizationId: 'your-org-id',
  apiKey: 'your-spect-api-key',
});

const result = await generateText({
  model: wrappedModel,
  prompt: 'Hello!',
});

Operation names

Set the trace operation name with provider options. Spect generates trace IDs automatically.

await generateText({
  model: wrappedModel,
  prompt: 'Hello!',
  providerOptions: {
    spect: {
      name: 'my-operation',
    },
  },
});

Sampling

Sampling is configured in the generic observer layer and applies to AI SDK + Claude Agent SDK wrappers.

const wrappedModel = wrap(openai('gpt-4o'), {
  organizationId: 'your-org-id',
  apiKey: 'your-spect-api-key',
  sampling: {
    rate: 0.1,
    key: ['operationName'],
    promote: {
      onError: true,
      minDurationMs: 5000,
      minTotalTokens: 20000,
    },
    rules: [
      {
        name: 'prod-agent',
        sampleRate: 1,
        match: {
          operationName: 'agent-prod',
          metadata: { env: 'prod' },
        },
      },
    ],
  },
});

Per AI SDK call override:

await generateText({
  model: wrappedModel,
  prompt: 'Hello!',
  providerOptions: {
    spect: {
      sampling: {
        rate: 0,
      },
    },
  },
});

Claude Agent SDK:

import { query } from '@anthropic-ai/claude-agent-sdk';
import { wrapQuery } from '@spect-tools/track';

const spectQuery = wrapQuery(query, {
  organizationId: 'your-org-id',
  apiKey: 'your-spect-api-key',
  sampling: {
    rate: 0.1,
    promote: { onError: true },
  },
});

const session = spectQuery({
  prompt: 'Build a hello world app',
  options: {
    model: 'claude-sonnet-4-6',
  },
});

Claude Agent SDK

Track Claude Agent sessions:

import { query } from '@anthropic-ai/claude-agent-sdk';
import { wrapQuery } from '@spect-tools/track';

const spectQuery = wrapQuery(query, {
  organizationId: 'your-org-id',
  apiKey: 'your-spect-api-key',
});

const session = spectQuery({
  prompt: 'Build a hello world app',
  options: {
    model: 'claude-sonnet-4-6',
  },
});

for await (const message of session) {
  console.log(message);
}

Telemetry integration (AI SDK)

Register Spect telemetry with the AI SDK. Requires ai@^7:

import { registerTelemetry } from 'ai';
import { SpectTelemetry } from '@spect-tools/track/ai-sdk-telemetry';

registerTelemetry(
  new SpectTelemetry({
    organizationId: 'your-org-id',
    apiKey: 'your-spect-api-key',
  })
);

Local Development Mode

Skip sending traces to collector (useful for local dev):

const wrappedModel = wrap(openai('gpt-4o'), {
  organizationId: 'your-org-id',
  local: true,
  onTrace: (payload) => console.log('Trace:', payload),
});

Viewer Component (React)

Embed a trace viewer in your app:

import { Viewer } from '@spect-tools/track/components';

export default function App() {
  return (
    <div>
      <Viewer spectBaseUrl="https://spect.tools" />
    </div>
  );
}

The Viewer polls for local traces and provides a button to open them in Spect.

Configuration Options

These top-level options are accepted by wrap(), wrapQuery(), and createObserver(). For the manual observer, startSession({ name }) sets the operation name for that session; operationName is only the fallback when a session name is omitted.

| Option | Type | Required | Description | |--------|------|----------|-------------| | organizationId | string | Yes | Your organization identifier | | apiKey | string | Yes, unless local: true | Spect API key | | collectorUrl | string | No | Collector URL (default: https://collect.spect.tools) | | provider | string | No | Fallback provider name when the wrapped model or session model does not provide one | | operationName | string | No | Default operation name for wrapper traces or unnamed manual sessions | | sampling | SamplingOptions | No | Sticky rate sampling, promotion rules, and rule-based overrides | | local | boolean | No | Local-only mode: skip collector, persist to .spect/data.json | | onTrace | (payload) => void | No | Callback when a trace is collected | | sendFailuresToConsole | boolean | No | Log collector send failures (default: true) | | headers | HeadersInit | No | Additional collector request headers | | fetchImpl | typeof fetch | No | Custom fetch implementation |

AI SDK calls also accept per-call providerOptions.spect values:

| Option | Type | Description | |--------|------|-------------| | name | string | Operation name for that call, unless top-level operationName is set | | metadata | Record<string, unknown> | Metadata attached to the trace request | | sampling | SamplingOptions | Per-call sampling override |

Local Trace Storage

Traces are only persisted to .spect/data.json when local: true. Access stored traces during development:

import { storeTrace, getLatest, get, list, clear } from '@spect-tools/track';

// Get latest trace
const latest = getLatest();

// Get all traces (up to 10 buffered)
const all = list();

// Get by ID
const trace = get('trace-id');

// Clear all stored traces
clear();

Traces are persisted to .spect/data.json when opted in and cleaned up on process exit.

Exports

Main (@spect-tools/track)

• wrapQuery(queryFn, spectOptions) - Claude Agent SDK query wrapper
• createObserver() - Generic observer for custom adapters
• generateTraceId() - Generate a unique trace ID
• storeTrace, getLatest, get, list, clear - Local storage utilities

AI SDK middleware (@spect-tools/track/ai-sdk-middleware)

Requires ai@^6 or ai@^7.

• wrap(model, options) - Wrap a language model with tracing
• spectMiddleware(options) - Get the middleware directly

AI SDK telemetry (@spect-tools/track/ai-sdk-telemetry)

Requires ai@^7.

• SpectTelemetry - AI SDK telemetry integration

Components (@spect-tools/track/components)

• Viewer - React component for in-app trace viewing

TypeScript

Types are included. Key exports:

import type {
  SamplingOptions,
  SamplingRule,
  SamplingPromotionOptions,
  SpectOptions,
  CollectorTracePayload,
} from '@spect-tools/track';