Sampling

Control trace volume with sticky rate sampling, retention rules, and match rules.

Baseline sampling

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

Adjust rate between 0 to 1 to sample 0% to 100% of traces. Use key to set the hash key for deterministic sampling.

Retention rules

For logs with errors, slow responses, or high token usage, you can configure Spect to always keep them.

const wrappedModel = wrap(openai('gpt-4o'), {
  organizationId: 'your-org-id',
  apiKey: 'your-spect-api-key',
  sampling: {
    rate: 0.05,
    promote: { 
      onError: true, 
      minDurationMs: 5000, 
      minTotalTokens: 20000, 
    }, 
  },
});

Rule-based overrides

For complex sampling, use rules to configure specific sampling rules for different operations, models, or metadata.

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

Rules can override:

sampleRate
key
promote

Usage on SDKs

AI SDK

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',
  },
});