Context Laravel Package

Product Decisions This Supports

• Standardize observability on OpenTelemetry rather than a proprietary tracing SDK. open-telemetry/context is the execution-scoped propagation primitive underneath the OTel PHP API/SDK. Adopting it signals a strategic choice: instrumentation is written once against a standard and exporters/backends (OTLP, Jaeger, Zipkin, Datadog, New Relic, Grafana) remain swappable. This is a roadmap commitment, not a library purchase.

• Decide where trace continuity actually breaks in Laravel, and fund that first. The package’s value concentrates exactly where PHP context is silently lost: queued jobs (Horizon/Redis/database), retries and chained jobs, scheduled Artisan commands, websocket/Octane/event-loop callbacks, and fiber-based concurrency. PM call: prioritize queue middleware and event-loop context binding over adding more dashboards, because a broken trace is a data-quality problem, not a visualization problem.

• Build vs. buy: adopt the context primitive, build the Laravel instrumentation. Do not build a bespoke correlation-ID mechanism. Take this package as the context layer and invest engineering effort in the parts OpenTelemetry does not give you for free: HTTP middleware, job wrappers, HTTP client hooks (Http::withTraceparent-style propagation), and log correlation that injects trace_id/span_id into Monolog context.

• Unlocks customer-facing observability features. Trace correlation enables support workflows like “follow this order from checkout through payment, fulfillment, and the nightly reconciliation job,” trace-aware error reports in Sentry/Bugsnag, and baggage-driven metadata such as tenant ID, request ID, or user segment flowing into logs and downstream services.

• Roadmap sequencing. Phase 1: instrument the request lifecycle and outbound HTTP clients. Phase 2: propagate through queues and scheduled jobs. Phase 3: cover async runtimes, fibers, and event loops. Phase 4: unify traces with logs/metrics and choose an exporter/backend strategy. This package is a dependency of that roadmap, not the roadmap itself — treat it as infrastructure, and budget for the surrounding work.

• Compliance-adjacent traceability, positioned honestly. Request/job trace correlation supports audits, incident postmortems, and data-flow analysis, but it is not a GDPR/PCI DSS control. Use it to make flows traceable; do not market it as a compliance solution.

• Risk decision: subtree-split dependency. The package is a read-only split of the opentelemetry-php monorepo. Version risk must be assessed against the monorepo’s release cadence and SDK/API compatibility, not against this package’s star count or its own release page in isolation.

When to Consider This Package

Consider adoption when:

• Your Laravel application is distributed or service-oriented, and diagnosing an incident requires correlating a request across HTTP calls, queues, and third-party APIs.
• OpenTelemetry PHP is already adopted or is the intended observability standard. This package is a low-level component; its value depends on the API/SDK, exporters, and instrumentation around it.
• You run queues (Horizon, Redis, database), scheduled jobs, websocket gateways, event loops, or fiber-based async code — the exact places where context loss produces incomplete traces.
• You need standard baggage propagation for tenant ID, request ID, workflow ID, or A/B segment across service boundaries and into logs.
• You are on a supported PHP version (the current monorepo baseline is PHP 8.2; the split package’s 1.x line dropped 7.4 and 8.0) and can accept OpenTelemetry’s model, including activate() / detach() scope discipline and try/finally hygiene.
• Your team can own instrumentation and configuration. This is plumbing, not a turnkey APM product.

Look elsewhere or deprioritize when:

• You only need local request logging, Laravel Debugbar, or Monolog context. A monolithic app with no distributed tracing requirement will not realize enough value to justify the dependency surface.
• You are not adopting OpenTelemetry and do not want to add SDK, exporter, and instrumentation complexity. A vendor APM agent or simpler log-correlation middleware is the better product decision.
• You need a complete managed observability solution. This package provides no dashboards, sampling policy, exporters, or automatic Laravel instrumentation.
• You depend on async behavior outside supported paths. Automatic fiber propagation requires an NTS build, ext-ffi, and OTEL_PHP_FIBERS_ENABLED; event loops require you to bind and restore context yourself. Validate in a spike before committing.
• Async workloads are trivial or fully synchronous — manual trace-ID logging is usually sufficient.
• Dependency-risk tolerance is low and the monorepo’s release cadence or SDK compatibility is uncertain for your support window.

Adoption caveats worth writing into the plan: debug scopes warn on missing detach() in non-production and are disabled via OTEL_PHP_DEBUG_SCOPES_DISABLED — expected notices in apps that use exit/die. Fiber support is environment-gated, so it belongs in a technical spike deliverable, not an assumption.

How to Pitch It (Stakeholders)

Executive summary. open-telemetry/context is a small but foundational piece of a standards-based observability strategy. It ensures a single user action can be followed across Laravel requests, background jobs, external APIs, and async workers without anyone building custom trace-correlation logic. The business value is faster incident diagnosis, better support workflows, and reduced lock-in to any one APM vendor. It is not a standalone monitoring product: it requires OpenTelemetry instrumentation and a backend before value is realized, so it should be funded as one line item inside an observability roadmap, not as a purchase that delivers monitoring on its own.

For engineering. Adopt it as the context-propagation primitive wherever OpenTelemetry PHP is in the stack. It gives you immutable contexts, execution-scoped activation, and explicit Scope::detach() semantics, plus debug scopes that surface missing detaches in non-production. Expect to own the Laravel-specific work: middleware to activate request context, queue and scheduled-job wrappers, HTTP client propagation, log correlation, and event-loop/fiber binding where relevant. Two constraints to plan around: fiber propagation needs an NTS build, ext-ffi, and the OTEL_PHP_FIBERS_ENABLED flag, and the package is a git subtree split of the monorepo — track the monorepo for release cadence, PHP version support, and SDK compatibility rather than evaluating this repo alone.

For product and support. This is the mechanism that lets us say “here is everything that happened to this order, including the job that ran at 2am” instead of stitching logs by hand. It enables trace-aware error reports, tenant/request baggage for filtered support views, and incident timelines that span synchronous and asynchronous work. It does not, on its own, produce dashboards, alerting, or compliance evidence — those remain separate decisions.