Skip to main content

​
Overview

The SDK includes built-in retry logic with exponential backoff. When a network request fails, it automatically retries with increasing delays, improving reliability in unstable network conditions.

​
Default Behavior

By default, the SDK:
  • Retries up to 3 times on failure
  • Uses 1000ms base backoff delay
  • Doubles the delay after each retry (exponential backoff)
Attempt 1: Immediate
Attempt 2: Wait 1000ms, then retry
Attempt 3: Wait 2000ms, then retry
Attempt 4: Wait 4000ms, then retry
→ Give up after 4 attempts

​
Configuration

Customize retry behavior per trace: 
const trace = client.trace({
  name: 'CriticalOperation',
  maxRetries: 5,        // Up to 5 retry attempts
  retryBackoff: 2000    // Start with 2 second delay
});

​
Options

OptionTypeDefaultDescription
maxRetriesnumber3Maximum retry attempts
retryBackoffnumber1000Base delay in milliseconds

​
Exponential Backoff

The delay doubles after each failed attempt:
AttemptDelay (default)Delay (2000ms base)
10ms (immediate)0ms
21000ms2000ms
32000ms4000ms
44000ms8000ms
58000ms16000ms

​
Use Cases

​
Critical Operations

For important data that must be delivered: 
const trace = client.trace({
  name: 'PaymentConfirmation',
  maxRetries: 10,       // More retry attempts
  retryBackoff: 500     // Start with shorter delay
});

​
Low-Priority Logging

For non-critical data where you want to fail fast: 
const trace = client.trace({
  name: 'AnalyticsEvent',
  maxRetries: 1,        // Only one retry
  retryBackoff: 100     // Quick retry
});

​
Disable Retries

Set maxRetries: 0 to disable retry logic: 
const trace = client.trace({
  name: 'NoRetry',
  maxRetries: 0  // Fail immediately on error
});

​
Error Handling

The SDK handles retries silently - your code doesn’t need to manage failures. However, if all retries are exhausted, the data is lost. For critical operations, consider:
  1. Using more retries
  2. Implementing application-level backup
  3. Monitoring for systematic failures
// Application-level fallback
const trace = client.trace({ name: 'CriticalData', maxRetries: 5 });

// Store locally as backup
try {
  localStorage.setItem('pendingTrace', JSON.stringify(traceData));
} catch (e) {
  // Handle storage errors
}

trace.addEvent('critical_event', traceData);

​
Network Conditions

The retry logic is especially useful for:
  • Mobile networks - Intermittent connectivity
  • Slow connections - Request timeouts
  • Server issues - Temporary 5xx errors
  • Rate limiting - Brief throttling periods

​
Best Practices

​
Match Retries to Importance

// Critical: payment confirmation
client.trace({ name: 'Payment', maxRetries: 10 });

// Important: user action
client.trace({ name: 'UserAction', maxRetries: 5 });

// Nice-to-have: analytics
client.trace({ name: 'Analytics', maxRetries: 2 });

​
Consider Total Time

With exponential backoff, retries can take significant time:
maxRetriesretryBackoffMax Total Time
31000ms~7 seconds
51000ms~31 seconds
52000ms~62 seconds

​
Don’t Over-Retry

Excessive retries can:
  • Block the flush queue
  • Delay subsequent traces
  • Waste bandwidth on permanent failures

​
Next Steps

TypeScript

Type-safe SDK usage

API Reference

Complete API documentation