How Distributed Tracing Context Survives Async Boundaries
Trace context across async: queues, workers, promises.
Here's how a trace dies. Not dramatically — it just stops updating halfway through a checkout flow. The HTTP spans look fine. The database queries show up. But the moment the request drops a job onto Redis and returns 202 Accepted, the trace flatlines. The BullMQ worker that processes that job never learns it belongs to the same transaction. The instrumentation isn't broken. Nobody wired up context propagation across the queue.
Most distributed tracing tutorials stop at the synchronous case: request comes in, you call another service over HTTP, you get a response. That's the easy part. The OpenTelemetry SDK handles it automatically.
But the second your system does anything async — setTimeout, message queues, worker threads, background jobs — you're on your own. The documentation gets thin. The examples get hand-wavy. And you end up on page four of a GitHub issues thread from 2022 wondering if anyone actually solved this problem or just gave up.
This post explains how distributed tracing context actually survives those async boundaries. We'll cover Node.js's AsyncLocalStorage (the magic behind automatic context propagation), W3C traceparent headers for cross-process handoff, and the patterns that make queue-based architectures traceable. By the end, you'll have OpenTelemetry code that traces requests from HTTP all the way through Redis queues, ready to send to an OpenTelemetry-native backend like JustAnalytics.
The problem: distributed tracing context doesn't cross process boundaries
Here's what synchronous tracing looks like — the case that "just works":
// HTTP handler — context propagates automatically
app.post('/checkout', async (req, res) => {
const span = tracer.startSpan('checkout.process');
// These database calls inherit the current span automatically
await db.createOrder(orderData);
await paymentService.charge(payment); // HTTP call — context in headers
span.end();
res.json({ success: true });
});
OpenTelemetry's auto-instrumentation handles the HTTP call to paymentService. It injects the trace ID into outbound headers, the receiving service extracts it, and both spans end up in the same trace. Magic.
Now here's the async case that breaks:
app.post('/checkout', async (req, res) => {
const span = tracer.startSpan('checkout.process');
await db.createOrder(orderData);
// Queue a background job
await queue.add('send-confirmation-email', { orderId: order.id });
span.end();
res.json({ success: true }); // Response returns immediately
});
// Worker process — separate Node.js instance
queue.process('send-confirmation-email', async (job) => {
// 🔴 What trace ID? This worker has no idea where the job came from.
await emailService.send(job.data.orderId);
});
The worker is a different process. It started independently. When it picks up the job, there's no HTTP request to extract headers from. The trace context died the moment we called queue.add().
AsyncLocalStorage: how Node.js threads context through callbacks
Before we fix the cross-process problem, we need to understand how context survives within a single Node.js process. The answer is AsyncLocalStorage, and it's genuinely clever.
When you do this:
import { AsyncLocalStorage } from 'node:async_hooks';
const asyncLocalStorage = new AsyncLocalStorage<{ traceId: string }>();
asyncLocalStorage.run({ traceId: 'abc-123' }, async () => {
// Context is available here
console.log(asyncLocalStorage.getStore()?.traceId); // 'abc-123'
await someAsyncOperation();
// Still available after awaits
console.log(asyncLocalStorage.getStore()?.traceId); // 'abc-123'
setTimeout(() => {
// Available in callbacks too
console.log(asyncLocalStorage.getStore()?.traceId); // 'abc-123'
}, 1000);
});
Node.js is tracking the async context through the event loop. Every Promise, every setTimeout, every callback created inside that run() block inherits the store. The runtime uses async hooks under the hood to propagate context through the microtask queue.
This is why OpenTelemetry "just works" for same-process async code. The SDK stores the current span in AsyncLocalStorage. When you await something, the context follows. When you call tracer.startSpan(), it automatically becomes a child of whatever span is currently in the store.
But. (There's always a but.)
AsyncLocalStorage doesn't cross process boundaries. It can't. The store lives in memory, and a queue worker is a different memory space entirely. It's an easy trap: assume context will "just work" across workers and you can lose days before the docs set you straight.
Pattern 1: explicit context injection into queue messages
The fix is surprisingly manual: serialize the trace context into the job payload, then restore it on the worker side.
// Producer side — inject context when queueing
import { context, propagation } from '@opentelemetry/api';
async function queueEmailJob(orderId: string) {
const carrier: Record<string, string> = {};
// Inject current trace context into a plain object
propagation.inject(context.active(), carrier);
await queue.add('send-confirmation-email', {
orderId,
_traceContext: carrier, // { traceparent: '00-abc123...', tracestate: '...' }
});
}
// Consumer side — extract and restore context
import { context, propagation, trace, SpanKind, SpanStatusCode } from '@opentelemetry/api';
// Bull-style consumer; in BullMQ, pass the same handler to new Worker(queueName, ...)
queue.process('send-confirmation-email', async (job) => {
const parentContext = propagation.extract(
context.active(),
job.data._traceContext || {}
);
const tracer = trace.getTracer('email-worker');
const span = tracer.startSpan(
'email.send',
{ kind: SpanKind.CONSUMER },
parentContext // 👈 Links this span to the original trace
);
try {
await context.with(trace.setSpan(parentContext, span), async () => {
await emailService.send(job.data.orderId);
});
span.setStatus({ code: SpanStatusCode.OK });
} catch (err) {
span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
throw err;
} finally {
span.end();
}
});
What's happening here:
-
propagation.inject() serializes the current span's trace ID, span ID, and trace flags into a plain object. This follows the W3C Trace Context format:
traceparent: 00-{trace-id}-{parent-span-id}-{flags}. -
The carrier object gets stuffed into the job payload. It's just data — strings that can serialize and deserialize across any transport.
-
propagation.extract() on the worker side reconstructs the context object from those strings.
-
tracer.startSpan() with a parent context creates a child span that belongs to the original trace.
-
context.with() runs the async work inside that restored context, so any downstream spans (like the email service call) also get linked.
Forgetting the context.with() wrapper is the classic mistake here. The span gets created correctly, but the nested calls never learn about it, and your spans sit there unconnected.
Pattern 2: header propagation for HTTP-based queues
Some queue systems — like AWS SQS, Google Cloud Tasks, or webhook-based workflows — already support headers. Use the same inject/extract pattern, but put the context in headers instead of the message body.
For AWS SQS, stuff the trace context into MessageAttributes:
await sqs.sendMessage({
QueueUrl: queueUrl,
MessageBody: JSON.stringify(payload),
MessageAttributes: {
traceparent: {
DataType: 'String',
StringValue: getTraceparentHeader(),
},
},
});
The receiving Lambda or consumer extracts from MessageAttributes the same way it would from HTTP headers. If you're using OpenTelemetry's AWS instrumentation, this might even happen automatically.
Pattern 3: worker threads within the same process
Worker threads are a middle ground — they're separate threads but same process. You'd think AsyncLocalStorage would work. It doesn't. Each worker thread has its own AsyncLocalStorage instance.
The fix is explicit message passing via postMessage:
// Main thread
import { Worker } from 'node:worker_threads';
import { propagation, context } from '@opentelemetry/api';
const carrier: Record<string, string> = {};
propagation.inject(context.active(), carrier);
const worker = new Worker('./heavy-computation.js');
worker.postMessage({
data: expensivePayload,
_traceContext: carrier
});
// Worker thread (heavy-computation.js)
import { parentPort } from 'node:worker_threads';
import { propagation, context, trace } from '@opentelemetry/api';
parentPort?.on('message', async (msg) => {
const parentContext = propagation.extract(context.active(), msg._traceContext || {});
const tracer = trace.getTracer('computation-worker');
const span = tracer.startSpan('heavy-computation', {}, parentContext);
// Do the work...
span.end();
parentPort?.postMessage({ result: computedValue });
});
Same pattern. Serialize context into the message, extract on the other side. The only difference is postMessage instead of a queue API.
Honestly? Worker threads are overused. Most workloads that "need" them would be fine with a proper job queue. But if your team already committed to worker threads, at least the context propagation is straightforward.
Gotcha: setTimeout and setInterval
These work automatically with AsyncLocalStorage — usually. But there's a subtle trap:
// ⚠️ Context is captured when setTimeout is called, not when the callback runs
const delayedSpan = () => {
const span = tracer.startSpan('delayed-work');
// ...
span.end();
};
setTimeout(delayedSpan, 5000);
If the parent span has already finished when the timeout fires, delayedSpan still becomes its child, because the context was captured when setTimeout was called. The trace stays connected, but the child starts after its parent ended, so the timing looks weird in your trace viewer.
If you want the span to cover the wait as well:
const span = tracer.startSpan('delayed-work');
setTimeout(async () => {
await context.with(trace.setSpan(context.active(), span), async () => {
// Work happens here, properly scoped
});
span.end();
}, 5000);
Either way the context comes from AsyncLocalStorage; the choice is only about what you want the span's duration to mean.
Putting it together with JustAnalytics
JustAnalytics is OpenTelemetry-native, so all these patterns wire directly into the platform. Apply the inject/extract pattern from Pattern 1 to your BullMQ jobs, and you'll see a single trace with all your spans: the HTTP checkout request, the queue delay while the job sat in Redis, and the worker processing.
When the email worker picks up the job and extracts context, its span joins the original checkout trace. If the email fails, the error status lands on the worker's span inside that same trace — no more correlating timestamps by hand.
That's the payoff.
Debugging goes from asking which request caused a failed email to clicking the trace ID and scrolling down. Debugging distributed systems without trace IDs means grepping logs sorted by timestamp. Life's too short. (For why logs, errors and traces belong in one place, see the case against the five-tool observability stack.)
Common errors and how to fix them
Spans appear but aren't linked (separate traces). You forgot propagation.extract() or didn't pass parentContext to startSpan(). The span gets created, but it starts a new trace instead of joining the existing one. Check that your carrier object actually contains traceparent — if it's empty, injection failed.
"Cannot read property 'traceId' of undefined" in worker. Your queue payload is being serialized in a way that strips the _traceContext field. Some ORMs and serializers can drop keys starting with underscores. Rename it to traceContext.
Trace context works in dev but not production. The propagator isn't registered. OpenTelemetry needs propagation.setGlobalPropagator(new W3CTraceContextPropagator()) called before you start tracing. Most SDK setup guides include this, but if you copy-pasted from a minimal example, you might have missed it.
Queue messages getting too large. The W3C traceparent header is 55 bytes, but if you're also propagating baggage or vendor-specific context (Datadog's x-datadog-* headers, for example), it can add up. For high-throughput queues, consider propagating only traceparent and reconstructing other context on the consumer side. (Or just accept the overhead. 55 bytes per message is nothing, and over-optimizing here is usually a distraction from bigger problems.)
Next steps
Now you've got context propagation across async boundaries — the piece most tracing tutorials skip. The next step is usually adding custom attributes to your spans so you can filter traces by business logic (user ID, order value, feature flags). For error correlation with your analytics data, our error-funnel correlation guide shows how to connect JustAnalytics error tracking with conversion events.
If you're running a Django backend instead of Node.js, the concepts are identical but the APIs differ — check our Django middleware tutorial for the Python version.
Copy the snippets. Break them. Trace them.
Frequently Asked Questions
Does AsyncLocalStorage work with Promise.all and concurrent awaits?
Yes. Each Promise in Promise.all inherits the context from where it was created, not from where it resolves. The AsyncLocalStorage store propagates through the microtask queue, so parallel awaits all share the same trace context as their parent. This is one of the things that makes AsyncLocalStorage nicer than manual threading — you don't have to pass context through every function signature.
What happens if my queue consumer crashes mid-job before acknowledging?
The worker's span for that attempt never ends, and OpenTelemetry SDKs only export a span when it ends, so the crashed attempt usually doesn't appear in the trace at all. When the job requeues and a new consumer picks it up, that second attempt gets a fresh span but carries the original trace context from the job, so it still joins the original trace.
Can I propagate trace context through WebSocket messages?
Yes, and you should. Treat each WebSocket message like an HTTP request — inject traceparent and tracestate into the message payload or a metadata field. The receiving end extracts context and creates a child span. For bidirectional flows, the server can send back its span ID so the client knows where to attach follow-up spans. It suits real-time collaboration features, where actions bounce between client and server multiple times.
How much overhead does context propagation add to queue throughput?
Negligible. The W3C traceparent header is 55 bytes. On a message queue processing 10K messages per second, that's about 550KB/sec of additional bandwidth — rounding error on any modern system. The CPU cost of parsing and generating trace IDs is similarly tiny. Measure it against your own workload if you're curious, but don't expect it to show up.
Try JustAnalytics
All-in-one observability in one under-5KB script: cookieless analytics + error tracking + APM + session replay + uptime + structured logs. Replaces GA4 + Sentry + Datadog + Pingdom + LogRocket. Free tier (100K events/mo), Pro $49/month ($39 annual).
Author at JustAnalytics.