Client Event Logger Redesign

​

What Changed

• Logging now uses coordinated batching/scheduling instead of a single queue.
• Retry behavior is now coordinated between batched events
  • batch-level retries (requeue + scheduled retry)
• Queue growth is explicitly bounded. Under sustained pressure, events may be dropped by design to protect stability.
• Limit Flushing and Scheduled Flushing due to size and time have been added
• The loggingIntervalMs option has been deprecated.

​

Architecture (High Level)

• PendingEvents: in-memory collection of newly logged events.
• BatchQueue: queue of batched events waiting to send.
• FlushCoordinator: controls flush timing and modes.
• EventSender: performs network sends and emits flush lifecycle events.
• FlushInterval: manages cooldown/backoff timing.

​

Flush Mechanisms

• Limit flush: flushes when a full batch is reached and backoff is satisfied. Limit flush performs opportunistic draining. Limit flush will keep flushing as long as each send over network is succesful. It will fall into backoff upon failure.
• Scheduled:full-batch flush: scheduler flushes full batches when cooldown allows.
• Scheduled:max-time flush: scheduler flushes partial batches when max interval (60s) is reached.
• Manual flush: explicit client.flush().
• Shutdown flush: best-effort on shutdown on explicit client.shutdown(), with persistence for shutdown-failed events in local storage.
• Quick flush: startup optimization for first-event latency. Flushes within 200ms window.

​

Retry Nuances

• Failed batches are requeued and retried.
  • Non-retryable errors are not requeued and are dropped.
  • Each batch gets 3 retries and are dropped after exceeding that threshold
• Backoff adjusts with success/failure and affects scheduled flush timing.

​

Drop Scenarios (Important)

• Batch queue overflow during batching/requeue. if there are more events in the batch queue than the capacity, the oldest batches are dropped.
  • queue capacity is batch size (default: 100) * max number of batches (30)
  • You can increase the queue capacity by increasing the batch size with the option loggingBufferMaxSize
• If the batch queue is full and we fail to requeue a failed batch, the entire batch is dropped.
• Non-retryable network failure.
• Max retries exceeded.
• Storage persistence failure (disabled/shutdown paths).
• Persisted-event cap exceeded (oldest events trimmed). Local storage has a hard maximum of 500 events.

​

Behavioral Impact for Upgrades

• Under very high throughput or long outages, event loss is possible by design.
  • According to your throughput and logging volume, adjust your batch size to avoid drooping events due to queue size limits. If you require higher throughput, contact Statsig Support.
• Non-retryable errors will drop events.
• Flushing cadence has changed. Instead of an adjustable background tick controlled flush, there are new flushing mechanisms which changes the flushing cadence and pattern.