Correlation IDs Across Go, PHP and Node (and One Immutable Surprise)
When a customer's loan application misbehaves, the thing you want is a single string that lets you pull every log line, from the browser-facing proxy to the last backend call, for that one journey. That string is a correlation ID, and it's one of those ideas that sounds trivial until you have three languages and a few dozen services.
The platform I worked on had a Node front end, PHP and Go APIs, GraphQL gateways and workers. It did not use the W3C traceparent header for correlation. It used its own header, something like X-Platform-Correlation-Id, alongside a separate APM product for traces. This post follows that header through the stack, because each hop shows a different lesson.
The four hops this post follows, and what each one does with the ID
Hop 1: the front-end proxy decides what gets through
The customer-facing web app talks to backend services through a thin proxy layer in the Node server. A proxy is where you can lose correlation silently, because proxies usually forward a curated list of headers, not all of them. This one used an allow-list:
const headerAllowList = [
// ...
'x-platform-api-key',
'x-platform-correlation-id',
'x-platform-tenant-id',
'x-platform-session-id',
];
if (headerAllowList.includes(key)) {
// forward it
}
An allow-list is the right default for security (you don't want arbitrary client headers reaching internal services), but it has a failure mode: every new cross-cutting header must be added by hand. If the correlation header weren't on this list, everything downstream would generate fresh IDs, and the first hop of every journey would be unsearchable. Treat the allow-list as part of your observability contract, with a test that asserts the correlation header survives the proxy.
Hop 2: PHP generates one if it's missing
The PHP API handles it in a PSR-15 middleware. If a request arrives with the header, use it. Otherwise, mint a UUID:
$correlationId = $request->getHeaderLine('X-Platform-Correlation-ID');
if (empty($correlationId)) {
$correlationId = Uuid::uuid4()->toString();
$request->withHeader('X-Platform-Correlation-ID', $correlationId);
}
LogContext::global()->add('correlation_id', $correlationId);
Two good ideas here and one subtle bug.
Good idea one: the log context is global for the request. Every log line written by any class in the request automatically carries correlation_id, with no one passing it around. That's how you get coverage without discipline.
Good idea two: generate at the edge if absent. A request that didn't come through the front end (a cron job, a partner API call) still gets an ID, so there's never a log line without one.
The bug: PSR-7 request objects are immutable. withHeader() doesn't change $request. It returns a new request with the header set. The return value above is discarded, so the generated ID is stored in the log context and the DI container, but the request that is passed on to the next handler still lacks the header.
$request = $request->withHeader('X-Platform-Correlation-ID', $correlationId);
In practice this may be invisible: the logs for this service carry the ID, because of the log context. It bites when downstream code reads the header from the request object (for example to forward it on an outgoing HTTP call), because in the generated-ID case it finds nothing. This is the kind of bug code review misses because the line reads correctly, and it's a good argument for a static-analysis rule (several PHP analysers flag "result of immutable with* call is unused").
Hop 3: Go reads it into the context and onto every log line
In Go the shared logger library captures both the ID and an "origin" header at the edge of the request, stores them in the context.Context, and adds them as structured fields on every entry:
const (
CorrelationIdKey key = "X-Platform-Correlation-Id"
CorrelationOriginKey key = "X-Platform-Correlation-Origin"
)
ctx = context.WithValue(ctx, CorrelationIdKey, r.Header.Get(string(CorrelationIdKey)))
// ...
if correlationId != "" {
fields[string(CorrelationIdKey)] = correlationId
}
The origin header is the underrated half. I didn't find its values documented, but the idea is clear: the ID says which journey, the origin says which system started it (a web journey, a batch import, a partner webhook, if you use it that way). In an incident, "show me everything from batch imports with this ID" is a very different query from "show me everything for this customer".
The same logger adds the APM trace and span IDs when a span is active, so a log line carries both identifiers: the business-level correlation ID and the trace ID. They answer different questions. The trace tells you where time went inside the call tree, while the correlation ID tells you which things belong to the same user journey, including asynchronous work that traces don't follow, like a worker picking up a queue message minutes later.
Hop 4: translating to someone else's convention
The last hop in this case was a call to an external partner's API, which required its own correlation headers. The Go transport that wraps those calls fills them in from the request context, and falls back to a fresh UUID when none is present:
reqID, _ := req.Context().Value(RequestID).(string)
sessID, _ := req.Context().Value(SessionID).(string)
if reqID == "" { reqID = uuid.NewString() }
if sessID == "" { sessID = uuid.NewString() }
req.Header.Set("X-Partner-Request-Correlation-Id", "ourco-"+reqID)
req.Header.Set("X-Partner-Session-Correlation-Id", "ourco-"+sessID)
There are three things I like here. First, a prefix identifies who generated the ID. When the partner's support team looks at their logs, ourco-... tells them immediately whose ID this is, which matters when two companies investigate the same incident. Second, request and session are separate. A session spans many requests, and having both lets the partner group the way you do. Third, there's always a value. Never sending an empty correlation header means the partner's logs for your calls are always joinable.
The caveat: in the code I read, those values come from RequestID and SessionID context keys set in the transport package, not from the inbound correlation header. Whether the two are linked depends on upstream code I didn't trace. If they aren't, the partner's ID and your correlation ID are two different strings for the same journey, and you'd want to log the pair at the moment you generate the outgoing one.
What I'd write on a whiteboard
- One header name, documented, used everywhere. Prefer an existing standard like
traceparentif you can, but whatever you choose, write it down. - Generate at the outermost edge only. Inner services should accept and propagate, and generate only as a fallback.
- Propagate by default. HTTP clients, queue publishers and job dispatchers should add the header automatically from context, not by developer memory.
- Test the contract at each proxy. A single end-to-end test that sends a known ID in and asserts it shows up in downstream logs would have caught both the allow-list risk and the immutable-request bug.
- Log the translation. When you convert your ID into someone else's, write both to your logs once.
Wrapping up
Correlation IDs fail at boundaries: proxies that filter headers, languages with different conventions, and immutable objects that look mutable. Each hop in this stack got the idea right, and each had its own way to lose the ID quietly. Treat every boundary as a place to add a test, not as an assumption, and log the pair whenever you translate your ID into someone else's.