correlation-tracing

SKILL.md

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

1d:[