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

> Understand web-tracing timeout and maxQueueLength. Learn how timeout aborts slow requests and maxQueueLength caches failed events to optimize your data sending configuration.

- Repository: [m-cheng-web/web-tracing](https://github.com/m-cheng-web/web-tracing)
- Tags: deep-dive
- Published: 2026-03-06

---

**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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/sendData.ts), this value is passed directly to the transport layer:

```typescript
// 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:

```typescript
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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/sendData.ts) enforces this limit before adding new events:

```typescript
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:

```typescript
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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/types/index.ts) within the `ReportOption` interface:

```typescript
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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/options.ts):

```typescript
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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/options.ts) and consumed by [`packages/core/src/lib/sendData.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/options.ts), type definitions live in [`packages/core/src/types/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/types/index.ts), and the runtime logic implementing these limits is located in [`packages/core/src/lib/sendData.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/sendData.ts) according to the m-cheng-web/web-tracing repository structure.