What Are web-tracing timeout and maxQueueLength? A Deep Dive into Data Sending Configuration

In web-tracing, timeout controls how long the SDK waits for a network request to complete before aborting it, while maxQueueLength limits how many failed events are cached in memory when the server is unreachable.

The web-tracing library batches telemetry events and transmits them to a configured DSN endpoint. Understanding the web-tracing timeout and maxQueueLength options is essential for tuning network resilience and preventing memory leaks in production applications.

How web-tracing Handles Data Transmission

The SDK collects log events and dispatches them via the SendData class. When the network is healthy, events transmit immediately using XMLHttpRequest or fetch. However, when the server returns a 5xx error or the network is offline, the library stores pending events in an in-memory queue for retry. The timeout and maxQueueLength options govern these two distinct failure modes.

Configuring Network Resilience with timeout

The timeout option defines the maximum duration (in milliseconds) that a single HTTP request is allowed to take before the SDK forcibly aborts it.

• Default value: 5000 (5 seconds)
• Purpose: Prevents stalled connections from blocking the event pipeline
• Failure behavior: The promise rejects with the error message @web-tracing XMLHttpRequest timeout

In packages/core/src/lib/sendData.ts, this value is passed directly to the transport layer:

// When initiating a request
sendByXML(url, data, options.value.timeout)

If your server endpoint experiences high latency or you are transmitting large payloads, increase this value to prevent premature abortions:

import { init } from '@web-tracing/core'

init({
  dsn: 'https://example.com/trace',
  timeout: 8000,  // Wait up to 8 seconds for each request
})

Managing Offline Events with maxQueueLength

The maxQueueLength option acts as a circuit breaker for memory consumption during server outages. When the SDK detects that the server is unavailable (network error or 5xx response), it queues events in memory for later transmission.

• Default value: 200 events
• Purpose: Caps memory usage by retaining only the most recent events when the backlog exceeds the limit
• Eviction policy: First-in-first-out (oldest events are dropped)

The implementation in packages/core/src/lib/sendData.ts enforces this limit before adding new events:

const maxQueueLength = options.value.maxQueueLength ?? 200
if (!this.isServerAvailable && this.events.length >= maxQueueLength) {
  // Retain only the newest maxQueueLength events
  this.events = this.events.slice(this.events.length - maxQueueLength + e.length)
}

This protects client applications from unbounded memory growth during prolonged outages. For high-traffic applications, increase this value to reduce data loss:

import { init } from '@web-tracing/core'

init({
  dsn: 'https://example.com/trace',
  maxQueueLength: 500,  // Cache up to 500 events during downtime
})

Type Definitions and Validation

Both options are formally declared in packages/core/src/types/index.ts within the ReportOption interface:

export interface ReportOption {
  timeout?: number           // Log report timeout in milliseconds
  maxQueueLength?: number   // Maximum cached events when server is unavailable
}

Default values and validation logic reside in packages/core/src/lib/options.ts:

export class Options {
  timeout = 5000           // ms, log-report request timeout
  maxQueueLength = 200     // Max cached events when server unavailable
  // ...
}

The SDK validates user-supplied values using validateOption(timeout, 'timeout', 'number') and validateOption(maxQueueLength, 'maxQueueLength', 'number') to ensure type safety at runtime.

Summary

• timeout (default 5000): Specifies the milliseconds to wait for an HTTP request before aborting it, preventing stalled connections from freezing the telemetry pipeline.
• maxQueueLength (default 200): Defines the in-memory event cap during server outages, automatically dropping oldest events to prevent memory exhaustion.
• Both options are defined in packages/core/src/lib/options.ts and consumed by packages/core/src/lib/sendData.ts during the transmission lifecycle.

Frequently Asked Questions

What happens when a web-tracing request exceeds the configured timeout?

The underlying XMLHttpRequest is aborted and the promise rejects with the error @web-tracing XMLHttpRequest timeout. The SDK treats this as a transmission failure and may queue the event for retry depending on your configuration.

Does increasing maxQueueLength impact browser memory usage?

Yes. The queue stores event objects in memory until the server becomes available or the page unloads. Setting maxQueueLength to a high value (e.g., 10000) increases the risk of memory pressure on low-end devices during extended network outages.

Can I disable the retry queue by setting maxQueueLength to zero?

Setting maxQueueLength to 0 would effectively prevent any event caching, causing immediate data loss during network interruptions. The library requires a positive integer; for always-fresh data, consider handling failures via the onError callback instead.

Where are timeout and maxQueueLength defined in the web-tracing source code?

Default values are declared in packages/core/src/lib/options.ts, type definitions live in packages/core/src/types/index.ts, and the runtime logic implementing these limits is located in packages/core/src/lib/sendData.ts according to the m-cheng-web/web-tracing repository structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}