Tail Sampling

1// Head sampling at 10% — RISKY!
2// You'll lose 90% of your errors too
3const shouldLog = Math.random() < 0.1
4if (shouldLog) {
5  await handleRequest()  // What if this errors?
6  log.info('Request completed')
7}

1// Tail sampling — SMART!
2// 100% of errors, 10% of success
3const event = createWideEvent({ type: 'http.request' })
4try {
5  await handleRequest()
6  event.end({ status: 'success' })
7} catch (error) {
8  event.end({ status: 'error', error })
9}
10 
11// Decision made AFTER we know the outcome
12logger.emitWideEvent(event) // Applies tail sampling internally

1import { createLogger } from 'vestig'
2 
3const logger = createLogger({
4  tailSampling: {
5    enabled: true,
6 
7    // Always keep these statuses (default: ['error'])
8    alwaysKeepStatuses: ['error', 'timeout'],
9 
10    // Always keep requests over 2 seconds
11    slowThresholdMs: 2000,
12 
13    // Keep 10% of successful requests
14    successSampleRate: 0.1,
15 
16    // VIP users get 100% sampling
17    vipUserIds: ['user-123', 'user-456'],
18 
19    // Premium tiers get 100% sampling
20    vipTiers: ['enterprise', 'premium'],
21 
22    // Where to find the tier (default: 'user.subscription')
23    tierFieldPath: 'user.subscription',
24  },
25})

1┌─────────────────────────────────────────────────────────┐
2│ 1. Is status in alwaysKeepStatuses? (error, timeout)   │
3│    YES → KEEP (100%)                                    │
4├─────────────────────────────────────────────────────────┤
5│ 2. Is duration >= slowThresholdMs?                     │
6│    YES → KEEP (100%)                                    │
7├─────────────────────────────────────────────────────────┤
8│ 3. Is userId in vipUserIds?                            │
9│    YES → KEEP (100%)                                    │
10├─────────────────────────────────────────────────────────┤
11│ 4. Is user tier in vipTiers?                           │
12│    YES → KEEP (100%)                                    │
13├─────────────────────────────────────────────────────────┤
14│ 5. Random sample at successSampleRate                  │
15│    Random < rate → KEEP                                 │
16│    Random >= rate → DROP                                │
17└─────────────────────────────────────────────────────────┘

1import { createTailSampler } from 'vestig'
2 
3const sampler = createTailSampler({
4  alwaysKeepStatuses: ['error'],
5  slowThresholdMs: 2000,
6  successSampleRate: 0.1,
7})
8 
9const result = sampler.shouldSample(completedEvent)
10 
11// result.sampled: boolean
12// result.reason: 'always_keep_status' | 'slow_request' |
13//                'vip_user' | 'vip_tier' |
14//                'random_sample' | 'random_drop'

1const logger = createLogger({
2  tailSampling: {
3    enabled: true,
4    alwaysKeepStatuses: ['error'],
5    slowThresholdMs: 5000,
6    successSampleRate: 0.01,  // 1% of success
7  },
8})

1const logger = createLogger({
2  tailSampling: {
3    enabled: true,
4    vipTiers: ['premium', 'enterprise'],
5    successSampleRate: 0.1,
6  },
7})

1const logger = createLogger({
2  tailSampling: {
3    enabled: true,
4    alwaysKeepStatuses: ['error', 'timeout', 'cancelled'],
5    successSampleRate: 0.05,  // 5% of successful jobs
6  },
7})

1const logger = createLogger({
2  tailSampling: {
3    enabled: true,
4    vipUserIds: ['debug-user-123'],  // Add user being debugged
5    successSampleRate: 0.1,
6  },
7})

1// middleware.ts
2import { createWideEventMiddleware } from '@vestig/next/wide-events'
3 
4export const middleware = createWideEventMiddleware({
5  tailSampling: {
6    enabled: true,
7    alwaysKeepStatuses: ['error'],
8    slowThresholdMs: 2000,
9    successSampleRate: 0.1,
10  },
11})

1// app/actions/user.ts
2'use server'
3 
4import { withWideEvent } from '@vestig/next/wide-events'
5 
6export const createUser = withWideEvent(
7  async (data, { event }) => {
8    event.set('user', 'email', data.email)
9    const user = await db.users.create({ data })
10    return user
11  },
12  {
13    name: 'action.user.create',
14    tailSampling: {
15      enabled: true,
16      successSampleRate: 0.1,
17    },
18  }
19)

1import { createTailSampler, createWideEvent } from 'vestig'
2 
3const sampler = createTailSampler({
4  alwaysKeepStatuses: ['error'],
5  successSampleRate: 0.1,
6})
7 
8const event = createWideEvent({ type: 'custom.operation' })
9// ... enrich event ...
10 
11const completedEvent = event.end({ status: 'success' })
12const { sampled, reason } = sampler.shouldSample(completedEvent)
13 
14if (sampled) {
15  logger.info('Wide event', completedEvent)
16  console.log(`Kept because: ${reason}`)
17}

1interface TailSamplingConfig {
2  /** Enable tail sampling (default: true) */
3  enabled?: boolean
4 
5  /** Always keep events with these statuses (default: ['error']) */
6  alwaysKeepStatuses?: ('success' | 'error' | 'timeout' | 'cancelled')[]
7 
8  /** Always keep events above this duration in ms */
9  slowThresholdMs?: number
10 
11  /** Sampling rate for successful events (0-1, default: 1.0) */
12  successSampleRate?: number
13 
14  /** VIP user IDs that always get 100% sampling */
15  vipUserIds?: string[]
16 
17  /** VIP subscription tiers that always get 100% sampling */
18  vipTiers?: string[]
19 
20  /** Field path to check for tier (default: 'user.subscription') */
21  tierFieldPath?: string
22}