aj-geddes/correlation-tracing

Correlation & Distributed Tracing

Table of Contents

• Overview
• When to Use
• Quick Start
• Reference Guides
• 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) | Correlation ID Middleware (Express) | | OpenTelemetry Integration | OpenTelemetry Integration | | Python Distributed Tracing | Python Distributed Tracing | | Manual Trace Propagation | 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