Google Cloud Trace Bundle Laravel Package

Product Decisions This Supports

• Observability strategy: native Cloud Trace vs. OpenTelemetry. This package is a forcing function to answer the question "what is our tracing standard?" before we start instrumenting services one by one. Adopting a Symfony-specific bundle into a Laravel/PHP estate is a decision to not standardize; the PM's job is to pick the abstraction (OTel) once rather than approve per-service integrations that each carry their own maintenance cost.
• Build vs. buy vs. read. The honest read on this package is that it is a specification, not a dependency. Its value to us is a documented, battle-tested answer to three questions we would otherwise guess at: how to parse inbound X-Cloud-Trace-Context, how to propagate it outbound, and what span attribute names the GCP Trace UI actually renders. That converts a "buy" decision into a cheap "read and reimplement" decision — a much smaller scope ask than it first appears.
• A roadmap input for the platform team, not a feature input. Tracing is a platform capability. It should be sequenced before the first service-to-service latency incident, not after. If we have a GCP-hosted stack and no cross-service tracing, that is a latent incident-response gap and belongs on the platform roadmap as a risk item, not a nice-to-have.
• Scoping the "observability for free" promise. Sales/leadership will assume distributed tracing is a checkbox. This assessment is the artifact that converts that assumption into a real estimate: 1–2 engineering weeks for a Laravel wrapper with propagation and failure-mode hardening, or a sprint of work to timebox an OTel rollout.
• Framework-consolidation signal. The fact that our candidate package is Symfony-only while the estate is Laravel is itself a product signal: our ecosystem assumptions and our dependency reality are drifting. Worth flagging in any platform-portfolio review.
• Licensing gate as a real decision. AGPL-3.0 is not a footnote on the decision record. For internal-only infrastructure this is usually tolerable; for anything that is distributed, resold, or offered to customers as part of a hosted service, it opens a copyleft question. Legal/OSS review should be a precondition on adoption, not a post-approval cleanup step.

When to Consider This Package

Consider it (as a reference implementation) when:

• We have committed to Google Cloud Trace as the backend and need the exact header contract and span-naming conventions to make our traffic render correctly alongside GCP-native services (GKE, Cloud Run, load balancers) that already emit those traces.
• The estate is Symfony, not Laravel — in which case the calculus changes entirely and the bundle's auto-wiring (kernel listener, DI config tree, HTTP client decoration) is genuinely cheaper than hand-rolling an exporter lifecycle.
• We need to trace a small number of services and want the shortest path to "spans visible in the console" for a spike.
• We want a concrete, readable prior art for how sampling decisions and trace-exclusion rules should be structured, without inheriting anyone's code.

Look elsewhere when:

• The target service is Laravel. There is no service provider, facade, or publishable config here; php artisan package:discover finds nothing. Any ticket describing this as a "drop-in Laravel package" is wrong and should be corrected before engineering time is committed.
• We need queue/async instrumentation. This bundle does not address it at all. Trace context carried through jobs is usually a first-order requirement in our stack and is the single biggest missing capability.
• We need vendor support or a support window. There is none. A 0-star, single-maintainer project means our priorities are not upstream's, and we should expect to carry our own patches.
• The company has any path to distributing or reselling the artifact — the AGPL copyleft obligation needs to be settled first.
• We expect tracing to be a multi-year, multi-language investment. An OTel-based stack is less total work than porting a framework-specific bundle, and it survives framework changes.

Default recommendation: treat this as a read-only reference, adopt google/cloud-trace or OTel as the actual dependency, and put a hard timebox (roughly one sprint) on any wrapper work with a fallback to OTel if the box is exceeded.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version: We evaluated a Google Cloud Trace integration for our PHP services. It is a mature-in-concept but niche Symfony component, and it does not work in our Laravel services without us writing and owning an adapter. The capability is worth having — without cross-service tracing, diagnosing "why is checkout slow" becomes guesswork across five systems. The package is not worth taking on as a dependency. Our recommendation is to adopt a framework-agnostic tracing library (OpenTelemetry) and use this package only as a reference for how to format trace headers so our services appear correctly in Google Cloud's console. Estimated cost: one to two engineering weeks, mostly in hardening, not in the happy path. This is a risk-reduction spend, not a feature spend — the value shows up the first time an incident crosses a service boundary.

For engineering — what we are actually asking for:

• Do not composer require this into a Laravel service and expect it to boot. It won't.
• Build the thin layer yourself: a service provider that binds a tracer only when GCP credentials and project ID are present and the environment is not local/testing, a global middleware that opens a root span from the inbound trace header and closes it in terminate() so error responses still produce spans, and a Guzzle/Http::withMiddleware hook that injects the outbound header on every downstream call. That outbound propagation is the highest-value 50 lines in the whole project — it is what makes traces stitch across services instead of showing up as isolated islands.
• Steal the bundle's header parsing and span attribute naming verbatim so our spans render correctly next to GCP-native ones.
• Harden the failure path before rollout, not after. Trace export must degrade to a silent no-op — a telemetry outage must never cause a request failure. Malformed inbound trace headers are untrusted input and must not throw.
• Explicitly configure sampling behind an env flag and start well below 1.0. Do not inherit a default of "trace everything"; it is a p99 latency and a billing problem.
• Two things that bite silently: credential misconfiguration produces missing traces, not exceptions, so alert on the absence of spans; and batch exporters can drop spans when a short-lived PHP-FPM request exits before flush, so flush explicitly on terminate.
• Release notes for the current version are a bare changelog link. Read the diff before any bump — a config-key rename in a minor version is the most likely break, and we own that risk because upstream never tested our integration.
• If the adapter work exceeds a one-sprint box, stop and switch to an OTel-based exporter. The fallback is cheap now and expensive later.