Cloud

Correlation IDs

Request and correlation ID propagation for distributed tracing.

2 min readDocumentationEdit this page

Overview

The correlation ID middleware assigns a unique request ID to every incoming request and propagates a correlation ID across service boundaries. Both IDs are attached to req.locals and injected into response headers.

Usage

typescript
import { correlationId } from '@axiljs/cloud'
 
app.use(correlationId())
 
app.get('/api/data', (req, res) => {
  console.log(req.locals.requestId)     // 'req_a1b2c3d4e5f6g7h8'
  console.log(req.locals.correlationId) // 'corr_x9y8z7w6v5u4t3s2'
  res.json({ data: '...' })
})

Response Headers

The middleware automatically echoes IDs in response headers:

HeaderDescription
X-Request-IdUnique ID for this specific request
X-Correlation-IdShared ID across a chain of service calls

Propagating Across Services

When calling downstream services, forward the correlation ID:

typescript
const response = await fetch('http://payment-service:3002/charge', {
  headers: {
    'X-Correlation-Id': req.locals.correlationId,
    'X-Request-Id': req.locals.requestId,
  },
})

The downstream service's correlationId() middleware will preserve the incoming correlation ID while generating a new request ID.

Options

typescript
app.use(correlationId({
  headerName: 'x-correlation-id',    // Incoming correlation header
  requestIdHeader: 'x-request-id',   // Incoming request ID header
  generateIfMissing: true,           // Auto-generate if not present
}))

Integration with Observability

Correlation IDs integrate with @axiljs/observability tracing:

typescript
import { Tracer, observabilityMiddleware } from '@axiljs/observability'
 
const tracer = new Tracer({ serviceName: 'my-api' })
 
app.use(correlationId())
app.use(observabilityMiddleware({ metrics, tracer }))
// Trace spans will include the correlation ID as an attribute

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License ยท Built by SyntaxilitY