Advanced Sampling

1LogEntry
2                       |
3                       v
4            +--------------------+
5            | Composite Sampler  |
6            +--------------------+
7            | Bypass Rules:      |
8            | - alwaysSampleErrors|
9            | - bypassLevel      |
10            +--------------------+
11                       |
12                       v
13            +--------------------+
14            |   Inner Sampler    |
15            | (Probability |     |
16            |  RateLimit |       |
17            |  Namespace)        |
18            +--------------------+
19                       |
20                       v
21              Sample: true/false

1import { createLogger, createProbabilitySampler } from 'vestig'
2 
3const logger = createLogger({
4  sampling: {
5    enabled: true,
6    sampler: createProbabilitySampler({ probability: 0.1 }), // 10%
7  }
8})
9 
10// ~10% of these logs will be kept
11logger.info('Regular event')

1import { createLogger } from 'vestig'
2 
3const logger = createLogger({
4  sampling: {
5    enabled: true,
6    sampler: 0.1, // Shorthand: 10% probability
7  }
8})

1import { createLogger, createRateLimitSampler } from 'vestig'
2 
3const logger = createLogger({
4  sampling: {
5    enabled: true,
6    sampler: createRateLimitSampler({
7      maxPerSecond: 100, // Max 100 logs per second
8    }),
9  }
10})
11 
12// First 100 logs each second are kept
13// Additional logs are dropped until next window

1const sampler = createRateLimitSampler({
2  maxPerSecond: 1000,
3  windowMs: 100, // 100ms window = finer granularity
4})

1// With maxPerSecond: 100
2 
3// Second 0: First 100 logs kept, rest dropped
4for (let i = 0; i < 500; i++) {
5  log.info('Burst log') // Only first 100 kept
6}
7 
8// Second 1: Counter resets, next 100 logs kept
9await sleep(1000)
10for (let i = 0; i < 500; i++) {
11  log.info('Burst log') // Only first 100 kept
12}

1import { createLogger, createNamespaceSampler } from 'vestig'
2 
3const logger = createLogger({
4  sampling: {
5    enabled: true,
6    sampler: createNamespaceSampler({
7      // Default for unmatched namespaces
8      default: 0.1, // 10%
9 
10      namespaces: {
11        // Exact matches
12        'auth': 1.0,     // Keep all auth logs
13        'payment': 1.0,  // Keep all payment logs
14 
15        // Wildcard patterns
16        'http.*': 0.5,   // 50% of HTTP logs
17        'db.*': 0.25,    // 25% of database logs
18      }
19    })
20  }
21})

1createNamespaceSampler({
2  default: 0.1,
3  namespaces: {
4    'api.users': 0.8,     // 80% - exact match, takes priority
5    'api.*': 0.2,         // 20% - for other api namespaces
6  }
7})

1createNamespaceSampler({
2  default: { probability: 0.1 },
3 
4  namespaces: {
5    // Probability for API logs
6    'api.*': { probability: 0.5 },
7 
8    // Rate limit for database logs
9    'db.*': { maxPerSecond: 50 },
10  }
11})

1const logger = createLogger({
2  sampling: {
3    enabled: true,
4    sampler: 0.1,
5    alwaysSampleErrors: true, // Default: true
6  }
7})
8 
9// Sampled at 10%
10log.debug('Debug info')
11 
12// Never sampled (has error)
13log.error('Critical failure', { error: new Error('Failed') })

1const logger = createLogger({
2  sampling: {
3    enabled: true,
4    sampler: 0.1,
5    bypassLevel: 'warn', // 'warn' and 'error' bypass sampling
6  }
7})
8 
9// Sampled at 10%
10log.debug('Debug info')
11log.info('Info message')
12 
13// Never sampled (at or above 'warn')
14log.warn('Warning message')
15log.error('Error message')

1import { createCompositeSampler, createRateLimitSampler } from 'vestig'
2 
3const innerSampler = createRateLimitSampler({ maxPerSecond: 100 })
4 
5const sampler = createCompositeSampler(innerSampler, {
6  alwaysSampleErrors: true,
7  bypassLevel: 'warn',
8})
9 
10const logger = createLogger({
11  sampling: {
12    enabled: true,
13    sampler,
14  }
15})

1import type { Sampler, LogEntry } from 'vestig'
2 
3// Sample based on user type
4const userBasedSampler: Sampler = {
5  shouldSample(entry: LogEntry): boolean {
6    const userId = entry.context?.userId as string
7 
8    // Always keep logs for premium users
9    if (userId?.startsWith('premium_')) {
10      return true
11    }
12 
13    // 50% for regular users
14    if (userId) {
15      return Math.random() < 0.5
16    }
17 
18    // 10% for anonymous
19    return Math.random() < 0.1
20  }
21}

1class ReservoirSampler implements Sampler {
2  private reservoir: LogEntry[] = []
3  private readonly maxSize: number
4  private count = 0
5 
6  constructor(maxSize: number) {
7    this.maxSize = maxSize
8  }
9 
10  shouldSample(entry: LogEntry): boolean {
11    this.count++
12 
13    // Always include first N entries
14    if (this.reservoir.length < this.maxSize) {
15      this.reservoir.push(entry)
16      return true
17    }
18 
19    // Probabilistically replace entries
20    const j = Math.floor(Math.random() * this.count)
21    if (j < this.maxSize) {
22      this.reservoir[j] = entry
23      return true
24    }
25 
26    return false
27  }
28 
29  destroy(): void {
30    this.reservoir = []
31    this.count = 0
32  }
33}

1class ConsistentSampler implements Sampler {
2  private readonly rate: number
3 
4  constructor(rate: number) {
5    this.rate = Math.max(0, Math.min(1, rate))
6  }
7 
8  shouldSample(entry: LogEntry): boolean {
9    const key = entry.context?.requestId ?? entry.timestamp
10    const hash = this.hashString(String(key))
11    return hash < this.rate
12  }
13 
14  private hashString(str: string): number {
15    let hash = 0
16    for (let i = 0; i < str.length; i++) {
17      const char = str.charCodeAt(i)
18      hash = ((hash << 5) - hash) + char
19      hash = hash & hash // Convert to 32bit integer
20    }
21    // Normalize to 0-1
22    return Math.abs(hash) / 2147483647
23  }
24}

1const getSamplingConfig = () => {
2  if (process.env.NODE_ENV === 'development') {
3    return { enabled: false } // Keep all logs in dev
4  }
5 
6  if (process.env.NODE_ENV === 'staging') {
7    return {
8      enabled: true,
9      sampler: 0.5, // 50% in staging
10    }
11  }
12 
13  // Production: aggressive sampling
14  return {
15    enabled: true,
16    sampler: createNamespaceSampler({
17      default: 0.1,
18      namespaces: {
19        'auth.*': 1.0,
20        'payment.*': 1.0,
21        'http.*': 0.05,
22        'cache.*': 0.01,
23      }
24    }),
25    alwaysSampleErrors: true,
26    bypassLevel: 'warn',
27  }
28}
29 
30const logger = createLogger({
31  sampling: getSamplingConfig(),
32})

1import { getContext, createProbabilitySampler } from 'vestig'
2 
3const traceSampler: Sampler = {
4  // Cache sampling decision per trace
5  private decisions = new Map<string, boolean>()
6 
7  shouldSample(entry: LogEntry): boolean {
8    const traceId = entry.context?.traceId as string
9    if (!traceId) {
10      return Math.random() < 0.1 // 10% for untraced
11    }
12 
13    // Return cached decision for this trace
14    if (this.decisions.has(traceId)) {
15      return this.decisions.get(traceId)!
16    }
17 
18    // Make and cache decision
19    const decision = Math.random() < 0.1
20    this.decisions.set(traceId, decision)
21 
22    // Cleanup old decisions (simple LRU)
23    if (this.decisions.size > 10000) {
24      const firstKey = this.decisions.keys().next().value
25      this.decisions.delete(firstKey)
26    }
27 
28    return decision
29  }
30}

1class AdaptiveSampler implements Sampler {
2  private logCount = 0
3  private lastReset = Date.now()
4  private currentRate = 1.0
5 
6  private readonly targetPerSecond: number
7  private readonly minRate: number
8  private readonly maxRate: number
9 
10  constructor(opts: {
11    targetPerSecond: number
12    minRate?: number
13    maxRate?: number
14  }) {
15    this.targetPerSecond = opts.targetPerSecond
16    this.minRate = opts.minRate ?? 0.01
17    this.maxRate = opts.maxRate ?? 1.0
18  }
19 
20  shouldSample(entry: LogEntry): boolean {
21    this.logCount++
22 
23    // Recalculate rate every second
24    const now = Date.now()
25    if (now - this.lastReset >= 1000) {
26      // Adjust rate based on actual throughput
27      const actualRate = this.logCount
28      const ratio = this.targetPerSecond / Math.max(actualRate, 1)
29 
30      this.currentRate = Math.max(
31        this.minRate,
32        Math.min(this.maxRate, this.currentRate * ratio)
33      )
34 
35      this.logCount = 0
36      this.lastReset = now
37    }
38 
39    return Math.random() < this.currentRate
40  }
41}

1// Sampler function signature
2type SamplerFn = (entry: LogEntry) => boolean
3 
4// Probability sampler config
5interface ProbabilitySamplerConfig {
6  probability: number // 0-1
7}
8 
9// Rate limit sampler config
10interface RateLimitSamplerConfig {
11  maxPerSecond: number
12  windowMs?: number // default: 1000
13}
14 
15// Namespace sampler config
16interface NamespaceSamplerConfig {
17  default?: SamplerConfig
18  namespaces?: Record<string, SamplerConfig>
19}
20 
21// Union type for sampler config
22type SamplerConfig =
23  | number // Shorthand for probability
24  | ProbabilitySamplerConfig
25  | RateLimitSamplerConfig
26  | NamespaceSamplerConfig
27 
28// Full sampling config
29interface SamplingConfig {
30  enabled?: boolean
31  sampler?: SamplerConfig
32  alwaysSampleErrors?: boolean // default: true
33  bypassLevel?: LogLevel       // default: 'error'
34}
35 
36// Sampler instance interface
37interface Sampler {
38  shouldSample(entry: LogEntry): boolean
39  destroy?(): void
40}