Correlation Ids Bundle Laravel Package

Product Decisions This Supports

• Observability roadmap sequencing. Correlation IDs are the cheapest first rung of the tracing ladder: one middleware, one log field, one response header. Adopting (or building) this unblocks the "we can't debug a single request across our logs" complaint without committing to OpenTelemetry, a tracing vendor, or a service mesh. It is a defensible quarter-one observability deliverable.
• Build vs. buy (and the answer is likely "port," not "buy"). The functional surface is roughly 50–100 lines: read or generate an ID, attach it to the log context, echo it on the response, forward it outbound. A PM should frame the decision as "do we adopt a dependency or own a tiny internal primitive?" — because the package is a Symfony bundle, not a Laravel package, the integration cost in a Laravel app includes a service provider/bridge. The realistic recommendation is: use it as a reference implementation, port the behaviour into Laravel middleware + a Monolog processor, and avoid carrying a Symfony runtime dependency for a feature this small.
• MTTR and incident-response investment. Every support escalation ("customer says checkout failed at 14:02") currently costs engineer time reconstructing a request from timestamps. A correlation ID turns that into a single log query. This is a support-cost reduction decision, not a developer-ergonomics one — pitch it that way and it survives budget review.
• Standardisation contract ahead of scale. The high-leverage product decision is not the package; it is the org-wide contract: canonical header name (X-Correlation-ID vs X-Request-ID), ID format (UUIDv4/v7, ULID), trusted-upstream policy, and relationship to any existing trace ID. Publish this before a second service ships, or you get IDs that don't join at service boundaries — which defeats the entire investment.
• Gate on multi-service expansion. If the roadmap includes splitting the monolith or adding a second backend, "does a request carry a correlatable ID end-to-end?" is a sensible pre-condition for the first split. This package (or a port of it) is a legitimate checklist item for that gate.
• Trust-boundary product decision. Whether to trust an inbound X-Correlation-ID is a security-product call, not an engineering detail: trusting it lets any client write arbitrary strings into your logs and downstream traces. Default to regenerate at the edge, trust only from your own gateway, and document it.
• Async scope decision. Decide explicitly what a "request" means for queues, scheduled commands, and outbound HTTP pools. Without that decision, the ID's coverage is a happy-path illusion — the traces you actually need during an incident (failed jobs, timed-out downstream calls) are the ones that silently lack it.
• Duplicate-ID risk assessment. If Sentry, OpenTelemetry, or a mesh already injects a trace ID, adopting a second identifier creates two canonical IDs and ambiguous runbooks. This is a "do we need this at all?" decision to make before, not after, rollout.
• Deployment/runtime readiness. Octane and queue workers are long-lived processes; per-request state must be reset or logs get attributed to the wrong request. This is a small, testable, but genuinely embarrassing failure mode — worth a decision on whether the platform team owns the reset contract.

When to Consider This Package

Reasonable to evaluate when:

• The estate is Symfony/PHP, where a bundle auto-registers and the integration is genuinely a config publish plus composer require.
• You need a fast, reversible pilot — there is no schema change, no data migration, and rollback is deleting a middleware registration. That makes it a low-commitment spike in a single non-production service.
• You have no existing trace propagation (no OTel, no mesh, no APM-injected trace ID) and are starting from zero.
• You want a readable reference implementation to copy from rather than a dependency to depend on — the code is small enough to audit in an afternoon, and MIT licensing permits the port.
• You can tolerate pre-1.0 churn: pin 0.1.* exactly and re-read the changelog on every bump, because there is no published BC promise and the 0.1 release note is a commit-range link rather than actual notes.

Look elsewhere — or build the ~100-line internal version — when:

• The application is Laravel-native. A *Bundle-suffixed Symfony package will not auto-register; you will write a bridge service provider regardless, at which point the internal port is cheaper and drops a dependency.
• You already run OpenTelemetry, Sentry, or a service mesh. Then this is redundant or actively harmful (competing identifiers), and the right move is to surface the existing trace ID in logs and headers instead.
• You need support, SLAs, or a security response process. This is a zero-star, single-vendor, single-release (2024-08-22), no-CI-evidence, no-LTS component. Acceptable for a log field; not acceptable for something every service's logs structurally depend on unless you name an internal owner who can read the source.
• You need queue and outbound-HTTP propagation out of the box. Expect to build job payload capture, Guzzle/Http middleware, and worker-side restore yourself. "Async context loss" is the default, not the exception.
• Regulated or audit-sensitive environments where a dependency needs a maintenance commitment, CVE process, or vendor contact.
• Log-ingestion cost is already a visible line item. Correlation IDs belong in the message context — never as a promoted metric label or a DB index key, where cardinality costs scale linearly with traffic.
• You need guaranteed Octane/worker state isolation and cannot verify it from the source without a spike you're unwilling to fund.

Decision rule for the PM: if the stack is Laravel, treat this as "an MIT-licensed spec we implement ourselves in half a day." If the stack is Symfony and the team is small, treat it as "a pinnable 0.1 dependency with a named internal owner and an exit plan."

How to Pitch It (Stakeholders)

For executives — one paragraph: "We have a concrete, cheap fix for the most common support pain we hear: not being able to trace a single customer request across logs. The open-source package in front of us is a small, MIT-licensed utility that stamps every log line for a request with one ID and passes it downstream. It is genuinely low-risk in the sense that matters — no database changes, no migration, and a rollback that consists of deleting one line of configuration. The catch is maturity: it is a pre-1.0, single-maintainer, zero-adoption component, and it is written for Symfony rather than our Laravel stack, so the honest recommendation is to borrow the design, not the dependency — roughly half a day of engineering to implement the same behaviour natively. The real deliverable is the standard: one header name, one ID format, one trust policy, agreed across teams. That standard is what reduces time-to-diagnosis; the code is incidental."

For engineering — the framing that gets buy-in:

• Scope: middleware that resolves or generates an ID, a Monolog processor that injects it into structured context (not interpolated into the message string), a response header set in a finally path so 4xx/5xx carry it, outbound HTTP propagation, and job payload capture/restore.
• Non-negotiables: regenerate rather than trust inbound IDs from untrusted clients; reset the holder on terminate/job boundaries for Octane and queue workers; keep the key name identical across web, queue, and console.
• Effort: ~half a day of engineering plus a short cross-team agreement cycle on header name, ID format, and canonical-ID-vs-OTel. Reversible at any point.
• Exit plan: the integration surface should be a middleware registration plus a config file, so swapping to an internal implementation or to OTel later is a contained change.

For the security/compliance reviewer:

• The ID is opaque and contains no PII — resist any temptation to pack user identifiers into it; look those up separately.
• The only real attack surface is the inbound header: unvalidated, it permits log injection, unbounded log-field cardinality, and forged-trace pollution. Mitigation is a format/length validation plus a trusted-upstream allowlist, documented in the runbook.

What to explicitly not promise: out-of-the-box async propagation, upstream maintenance guarantees, or a permanent API. Pin the version, name an internal owner who has read the source, and treat the package — if adopted at all — as a pinned reference rather than a platform bet.