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 2 times on failure
  • Uses 500ms base backoff delay
  • Doubles the delay after each retry (exponential backoff)
Attempt 1: Immediate
Attempt 2: Wait 500ms, then retry
Attempt 3: Wait 1000ms, then retry
→ Give up after 3 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
maxRetriesnumber2Maximum retry attempts
retryBackoffnumber500Base delay in milliseconds

​
Exponential Backoff

The delay doubles after each failed attempt:
AttemptDelay (default)Delay (2000ms base)
10ms (immediate)0ms
2500ms2000ms
31000ms4000ms
42000ms8000ms
54000ms16000ms

​
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);

​
v2 Resilience Improvements

SDK v2 includes several improvements for handling high-volume and unreliable network conditions.

​
Flush Batching

Flush requests are batched — up to 100 items per flush. This reduces the number of network requests and improves throughput.

​
Rate Limiting

The SDK includes built-in rate limiting to prevent overwhelming the gateway during bursts of activity.

​
Keep-Alive Failure Handling

The keep-alive timer automatically stops after 3 consecutive failures, preventing wasted resources on dead connections. See Traces for details.

​
Queue Management

Each trace has a configurable flush queue with a default maximum size of 4096 items. When the queue is full, new items are dropped and the onDropped callback is invoked: 
const trace = client.trace({
  name: 'HighVolume',
  maxQueueSize: 8192,
  callbacks: {
    onDropped: (trace, reason) => console.warn('Dropped:', reason)
  }
});

​
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
2500ms~1.5 seconds
5500ms~15.5 seconds
51000ms~31 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