Sampling

Control what percentage of events are sent to Syntropy.

Why Sample?

For high-traffic applications, sampling helps:

• Reduce costs - Fewer events = lower storage
• Improve performance - Less network overhead
• Maintain visibility - Still catch errors, just not every instance

Sample Rate

Set a sample rate between 0.0 and 1.0:

Syntropy.init({
  projectId: 'your-project-id',
  sampleRate: 1.0,   // 100% - send all events (default)
  sampleRate: 0.5,   // 50% - send half of events
  sampleRate: 0.1,   // 10% - send 1 in 10 events
  sampleRate: 0.01,  // 1% - send 1 in 100 events
});

How It Works

When an event is captured, Syntropy generates a random number:

random() < sampleRate → send event
random() >= sampleRate → drop event

This is applied per-event, so you'll still see a representative sample of errors.

Recommendations

Traffic Level	Recommended Sample Rate
Low (under 10k events/day)	1.0 (100%)
Medium (10k-100k/day)	0.5 - 1.0
High (100k-1M/day)	0.1 - 0.5
Very High (over 1M/day)	0.01 - 0.1

Dynamic Sampling

Adjust sample rate based on conditions:

function getSampleRate() {
  // Higher sampling for errors, lower for other events
  return {
    error: 1.0,      // Always capture errors
    pageview: 0.1,   // Sample page views
    custom: 0.5,     // Sample custom events
  };
}

Syntropy.init({
  projectId: 'your-project-id',
  beforeSend: (event) => {
    const rates = getSampleRate();
    const rate = rates[event.type] ?? 1.0;
    
    if (Math.random() >= rate) {
      return null; // Drop based on type-specific rate
    }
    
    return event;
  },
});

Always Capture Critical Errors

Even with sampling, you might want to always capture certain errors:

Syntropy.init({
  projectId: 'your-project-id',
  sampleRate: 0.1, // 10% default
  beforeSend: (event) => {
    // Always send fatal errors
    if (event.payload.severity === 'fatal') {
      return event;
    }
    
    // Always send payment errors
    if (event.payload.tags?.component === 'payment') {
      return event;
    }
    
    // Apply normal sampling
    if (Math.random() >= 0.1) {
      return null;
    }
    
    return event;
  },
});

Session-Based Sampling

For consistent user experience tracking, sample by session:

// Decide once per session
const shouldSample = Math.random() < 0.1;

Syntropy.init({
  projectId: 'your-project-id',
  enabled: shouldSample, // All or nothing per session
});

This ensures you get complete sessions rather than random events.