Tracing Through Proxy and Gateway Layers

In this lesson, you will learn how to maintain a unified trace ID across proxy and gateway boundaries to ensure your distributed traces remain unbroken and represent the complete request lifecycle.

The Challenge of Fragmentation

When a request hits your infrastructure, it typically traverses several layers: a Load Balancer, an API Gateway, and finally your Node.js microservice. If each of these layers generates its own independent span or trace ID, your observability platform will see these as disconnected events rather than a single, coherent user request. This "fragmentation" makes debugging impossible because you cannot correlate the latency at the gateway with the execution logic inside your application.

The Propagation Pattern

To solve this, we rely on standard header propagation (like the W3C traceparent header). The ingress point—usually your API Gateway—must be responsible for extracting the incoming trace context or generating a new one if it’s missing.

Your Node.js service must then act as a "participant" in the trace, respecting the existing context rather than blindly starting a new one. Here is a conceptual example of how you might handle this in your middleware:

const { propagation, context } = require('@opentelemetry/api');

function handleIncomingRequest(req, res) {
  // 1. Extract the context from incoming headers
  const parentContext = propagation.extract(context.active(), req.headers);

  // 2. Start a new span as a child of the extracted context
  const span = tracer.startSpan('http_request', {}, parentContext);

  // 3. Bind the span to the current execution context
  context.with(trace.setSpan(parentContext, span), () => {
    // Process the request...
    span.end();
  });
}

Why Ingress is Critical

The proxy or gateway layer is the "source of truth" for the trace entry. If the proxy doesn't forward the trace headers, your backend service will perceive every request as a "root" span. By ensuring the gateway correctly passes the traceparent header into your Node.js application, you ensure that the trace_id remains constant throughout the request's journey. This allows your tracing tool to stitch together the proxy’s latency and your application’s logic into a single, seamless waterfall diagram.

Key Takeaway: To prevent trace fragmentation, your application must extract trace context from upstream headers rather than creating new root spans, ensuring the trace identity established at the gateway persists through the entire call chain.