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 HTTP request tracing?
- Use `Context::getCurrent()->activate()` in your middleware’s `handle()` method, wrap the `$next($request)` call in a `try-finally` block, and call `$scope->detach()` in the `finally` clause. This ensures context propagation across middleware layers without leaks. Example: `app/Http/Middleware/PropagateContext.php`.
- Does this package support Laravel’s async layers like Swoole or Horizon workers?
- Yes. For Swoole, use `bindContext()` to wrap job handlers or coroutines. For fibers, enable automatic propagation by setting `OTEL_PHP_FIBERS_ENABLED=1` (requires NTS PHP + FFI). Horizon workers and queues can propagate context via middleware or `bindContext()` in job execution hooks.
- Will this work with Laravel 10/11 and PHP 8.1+? Are there breaking changes?
- Fully compatible with Laravel 10/11 and PHP 8.1+. The package drops PHP 7.4/8.0 support, but this aligns with Laravel’s minimum requirements. No breaking changes exist for existing usage patterns. Test with PHP 8.4 if targeting the latest Laravel.
- How do I debug missing `detach()` calls in development?
- Enable debug scopes by default (non-production). If a scope isn’t detached, PHP will emit a warning. Disable warnings in production via `OTEL_PHP_DEBUG_SCOPES_DISABLED=1`. This helps catch leaks early, especially in long-running CLI commands like Artisan or queues.
- Can I use this with Laravel’s HTTP clients (Guzzle, Symfony HTTP Client) for trace propagation?
- Absolutely. Use `TextMapPropagator` to inject/extract context from HTTP headers. For Guzzle, wrap requests in a `bindContext()` closure or use middleware. Symfony HTTP Client supports propagation via `ContextClientMiddleware`. Baggage (custom metadata) will auto-propagate across service boundaries.
- What’s the performance impact of context activation/detachment in high-traffic Laravel apps?
- Minimal overhead for most use cases. Benchmark in staging with 10K+ RPS to validate. Optimize by limiting baggage size and avoiding deep nesting. The package is designed for low-latency propagation, but excessive baggage or nested scopes may require tuning.
- How do I propagate context to downstream services (e.g., queues, APIs) in Laravel?
- Use `Baggage` for custom metadata (e.g., `tenant_id`) and `TextMapPropagator` for HTTP headers. Ensure downstream services (e.g., queue workers, APIs) extract context using the same propagator. Laravel’s service container can auto-bind the propagator for consistency.
- Are there alternatives to OpenTelemetry Context for Laravel tracing?
- Proprietary options like Datadog APM or New Relic offer Laravel integrations, but they lack OpenTelemetry’s vendor-neutral standard. For open-source, consider `spatie/laravel-monitoring` (basic) or `ddtrace/dd-trace-php` (Datadog-specific). OpenTelemetry Context is the most future-proof for multi-backend observability.
- How do I handle context in Laravel Echo (WebSockets) or Pusher channels?
- Wrap WebSocket event handlers in `bindContext()` to propagate context to frontend clients. For Pusher, use middleware to inject context into channel payloads. Ensure the frontend SDK (e.g., OpenTelemetry JS) can extract baggage from WebSocket messages.
- What environment variables control debugging or fiber support?
- Debug scopes: `OTEL_PHP_DEBUG_SCOPES_DISABLED=1` (disable warnings). Fiber support: `OTEL_PHP_FIBERS_ENABLED=1` (requires NTS PHP + FFI). Preload `vendor/autoload.php` if `ffi.enable=preload` is set. Check the README for full configuration details.
Weaver
How can I help you explore Laravel packages today?