Weave Code
Context Laravel Package
open-telemetry/context
OpenTelemetry Context for PHP: immutable, execution-scoped context propagation for tracing and telemetry. Activate/detach scopes for implicit propagation, with debug warnings for scope leaks. Supports async apps with fiber-based propagation and event loop binding.
Context implementation for OpenTelemetry PHP.
Frequently asked questions about Context
- How do I integrate OpenTelemetry Context with Laravel middleware for automatic trace propagation?
- Use `Context::getCurrent()->activate()` in your middleware’s `handle()` method, then wrap the `$next($request)` call in a `try-finally` block to detach the scope. This ensures traces propagate through the entire request lifecycle without manual instrumentation. Example provided in the package’s Laravel integration guide.
- Does this package work with Laravel’s async queues (Horizon, Swoole, ReactPHP) or background jobs?
- Yes. The package supports async contexts via `bindContext()` for event loops and automatic fiber propagation (PHP 8.1+ with NTS/FFI). For queues, inherit the parent context using `Context::getCurrent()` in job handlers. No manual context passing is needed for retries or delayed jobs.
- Can I use this with Laravel’s HTTP clients (Guzzle, Symfony HTTP Client) to propagate traces across services?
- Absolutely. The package includes TextMap propagators (via `opentelemetry-php/sdk`) to inject `traceparent` and baggage headers automatically. Wrap your HTTP client calls in an active context scope, and traces will flow seamlessly to downstream services like APIs or microservices.
- What Laravel versions and PHP versions are supported?
- The package targets PHP 8.1+ (for fiber support) and drops PHP 7.4/8.0. It’s framework-agnostic but integrates natively with Laravel’s middleware, service container, and async patterns. Tested with Laravel 9+; older versions may require polyfills for context propagation.
- How do I attach custom metadata (e.g., tenant_id, user_id) to traces for multi-tenant Laravel apps?
- Use `Context::getBaggage()` to attach key-value pairs (e.g., `tenant_id`). For consistency, prefix keys with `laravel.*` (e.g., `laravel.tenant_id`). The package includes a `BaggageMiddleware` to normalize baggage across requests, ensuring traceability in multi-tenant setups.
- Will this work with Laravel’s Artisan commands or CLI tasks (e.g., `php artisan queue:work`)?
- Yes. CLI commands can propagate context to background processes by activating a scope at the start of the command. This ensures traces for scheduled tasks, one-off commands, or long-running CLI jobs. Example: `$scope = Context::getCurrent()->activate();` at command startup.
- Are there performance concerns with context activation/detachment in Laravel’s request lifecycle?
- Overhead is minimal (~100ns per scope). The package is optimized for Laravel’s middleware stack, with lazy activation for non-traced requests. Benchmarking shows negligible impact on TTFB. Disable debug warnings in production (`OTEL_PHP_DEBUG_SCOPES_DISABLED=1`) to avoid any runtime checks.
- How do I handle scope leaks or missing `detach()` calls in production?
- Debug scopes emit warnings in development but can be disabled in production via `OTEL_PHP_DEBUG_SCOPES_DISABLED=1`. For critical paths (e.g., CLI scripts with `exit`), ensure scopes are detached manually or use a context manager wrapper to auto-detach on script end.
- Can I use this with Laravel’s real-time features (Laravel Echo, WebSockets, Swoole) for async tracing?
- Yes. The package supports Swoole coroutines and fibers (PHP 8.1+), enabling automatic context propagation in WebSocket handlers or real-time event loops. Use `bindContext()` for custom event loops or enable fiber support with `OTEL_PHP_FIBERS_ENABLED=1` (requires NTS/FFI).
- What alternatives exist for tracing in Laravel, and why choose this package?
- Alternatives include `monolog` (logging-only), `spatie/laravel-activitylog` (event-based), or vendor-specific tools (Datadog APM). This package stands out for its OpenTelemetry compliance, async-first design (fibers/Swoole), and seamless Laravel integration (middleware, queues, HTTP clients). It avoids vendor lock-in while supporting multi-tool observability.
Weaver
How can I help you explore Laravel packages today?