express-trace-id

Lightweight Express middleware that automatically assigns a unique trace ID to every incoming request. Enables seamless request correlation for debugging, structured logging, and distributed system observability.

Table of Contents

• Installation
• Quick Start
• Logging Integration
• API Reference
  • traceId()
  • getTraceId()
  • X_TRACE_ID
• Validation
• License

Installation

npm install express-trace-id

Requires Node.js 14.x or higher and Express 4.x or 5.x.

Quick Start

const express = require("express");
const { traceId } = require("express-trace-id");

const app = express();

app.use(traceId());

app.get("/", (req, res) => {
  res.json({ traceId: req.traceId });
});

app.listen(3000);

Every request automatically receives:

• A unique trace ID available as req.traceId
• The trace ID in response headers as x-trace-id

Logging Integration

Use getTraceId() to access the trace ID anywhere in your request chain thanks to Node.js AsyncLocalStorage:

const express = require("express");
const { traceId, getTraceId } = require("express-trace-id");

const app = express();
app.use(traceId());

app.get("/users/:id", async (req, res) => {
  // Access via req.traceId
  console.log(`[${req.traceId}][GET /users/:id] Request started`);

  const user = await fetchUser(req.params.id);

  // Access via getTraceId() function
  const traceId = getTraceId();
  console.log(`[${traceId}][GET /users/:id] Request completed`);

  res.json({ user });
});

async function fetchUser(userId) {
  // Access via getTraceId() in async function
  const traceId = getTraceId();
  console.log(`[${traceId}][fetchUser] Fetching user ${userId}`);

  const user = await db.users.findById(userId);

  console.log(`[${traceId}][fetchUser] Found user ${user.name}`);

  return user;
}

app.listen(3000);

Log Output:

[a7f3e2d1-4b8c-4a5e-9f1d-8c7b6a5e4d3c][GET /users/:id] Request started
[a7f3e2d1-4b8c-4a5e-9f1d-8c7b6a5e4d3c][fetchUser] Fetching user 123
[a7f3e2d1-4b8c-4a5e-9f1d-8c7b6a5e4d3c][fetchUser] Found user John Doe
[a7f3e2d1-4b8c-4a5e-9f1d-8c7b6a5e4d3c][GET /users/:id] Request completed

All logs share the same trace ID, making it easy to track a request through your entire application.

API Reference

traceId()

Automatically generates a UUID v4 trace ID when not provided. Available via req.traceId, getTraceId(), or the x-trace-id header.

Usage:

app.use(traceId());

Returns 400 Bad Request if a custom trace ID fails validation.

getTraceId()

Retrieves the current request's trace ID from anywhere in your code.

Returns:

• string - The trace ID during a request
• "no-trace-id" - Outside a request context

Example:

function logError(error) {
  console.error(`[${getTraceId()}] Error:`, error.message);
}

X_TRACE_ID

Constant for the trace ID header name: "x-trace-id"

Example:

const { X_TRACE_ID } = require("express-trace-id");

app.get("/custom", (req, res) => {
  res.json({ traceId: req.header(X_TRACE_ID) });
});

Validation

Trace IDs must match: /^[a-zA-Z0-9_-]+$/

Valid:

• 550e8400-e29b-41d4-a716-446655440000 (auto-generated UUID)
• request_abc123
• trace-2024-001

Invalid:

• invalid@id (special characters)
• my trace id (spaces)

Custom trace IDs that fail validation return a 400 Bad Request response. For best results, let the middleware auto-generate UUIDs to ensure uniqueness and avoid collisions.

License

ISC

Author: Sion Young