/correlation-tracing

name: correlation-tracing
description: >
  Implement distributed tracing with correlation IDs, trace propagation, and
  span tracking across microservices. Use when debugging distributed systems,
  monitoring request flows, or implementing observability.

Correlation & Distributed Tracing

Table of Contents

• [Overview](#overview)
• [When to Use](#when-to-use)
• [Quick Start](#quick-start)
• [Reference Guides](#reference-guides)
• [Best Practices](#best-practices)

Overview

Implement correlation IDs and distributed tracing to track requests across multiple services and understand system behavior.

When to Use

• Microservices architectures
• Debugging distributed systems
• Performance monitoring
• Request flow visualization
• Error tracking across services
• Dependency analysis
• Latency optimization

Quick Start

Minimal working example:

import express from "express";
import { v4 as uuidv4 } from "uuid";

// Async local storage for context
import { AsyncLocalStorage } from "async_hooks";

const traceContext = new AsyncLocalStorage<Map<string, any>>();

interface TraceContext {
  traceId: string;
  spanId: string;
  parentSpanId?: string;
  serviceName: string;
}

function correlationMiddleware(serviceName: string) {
  return (
    req: express.Request,
    res: express.Response,
    next: express.NextFunction,
  ) => {
    // Extract or generate trace ID
    const traceId = (req.headers["x-trace-id"] as string) || uuidv4();
    const parentSpanId = req.headers["x-span-id"] as string;
    const spanId = uuidv4();
// ... (see reference guides for full implementation)

Reference Guides

Detailed implementations in the `references/` directory:

| Guide | Contents | |---|---| | [Correlation ID Middleware (Express)](references/correlation-id-middleware-express.md) | Correlation ID Middleware (Express) | | [OpenTelemetry Integration](references/opentelemetry-integration.md) | OpenTelemetry Integration | | [Python Distributed Tracing](references/python-distributed-tracing.md) | Python Distributed Tracing | | [Manual Trace Propagation](references/manual-trace-propagation.md) | Manual Trace Propagation |

Best Practices

✅ DO

• Generate trace IDs at entry points
• Propagate trace context across services
• Include correlation IDs in logs
• Use structured logging
• Set appropriate span attributes
• Sample traces in high-traffic systems
• Monitor trace collection overhead
• Implement context propagation

❌ DON'T

• Skip trace propagation
• Log without correlation context
• Create too many spans
• Store sensitive data in spans
• Block on trace reporting
• Forget error tracking