Correlation ID

Every request automatically generates a systemCorrelationId used internally for logging and error context. Optionally, you can forward it as an outgoing HTTP header to downstream services — enabling distributed tracing across your service mesh.

Why Correlation IDs Matter

In a distributed system, a single user action can trigger dozens of service-to-service calls. Without a shared identifier, correlating logs across services to diagnose a failure requires manual reconstruction. Propagating a correlation ID header makes the entire call chain visible in your log aggregator instantly.

Enabling Propagation

Correlation ID propagation is opt-in. Enable it on the adapter:

const adapter = HttpAdapter.builder()
  .withCorrelationId()                   // forwards as 'x-correlation-id' (default)
  .withCorrelationId('x-request-id')     // use a custom header name
  .build();

Every request sent through this adapter will include the header with a generated UUID.

Per-Request Overrides

Per-request configuration takes full precedence over the adapter-level setting:

// Enable for this request with a different header name
const request = new RequestBuilder('https://api.example.com')
  .setEndpoint('/payments')
  .withCorrelationId('x-trace-id')
  .build();

// Disable for this request entirely (adapter config is ignored)
const internalRequest = new RequestBuilder('https://api.example.com')
  .setEndpoint('/internal/health')
  .withoutCorrelationId()
  .build();

Header Resolution Order

When the adapter sends a request, the correlation ID header is resolved in this order:

1. Per-request header (.withCorrelationId('custom-header') on the builder)
2. Adapter-level header (.withCorrelationId('custom-header') on the adapter builder)
3. Default header — 'x-correlation-id'

If .withoutCorrelationId() is called on the request, no header is forwarded regardless of adapter config.

Accessing the Correlation ID

The correlationId is available on every RequestContext attached to exceptions:

} catch (error) {
  if (error instanceof BaseAdapterException) {
    logger.error({
      correlationId: error.requestContext?.correlationId,
      ...error.toJSON(),
    });
  }
}

This means any failure log will contain the correlation ID — making it trivial to search your log aggregator for all events belonging to a single request chain.