open-telemetry / open-telemetry/opentelemetry-php
[opentelemetry-php-contrib] Laravel: Termination phase of request handling not part of root-span
Nobody has claimed this yet.
- Dominant language
- PHP
- Stars
- 912
- Forks
- 232
- Avg merge
- 7d 16h
- Merged PRs (30d)
- 4
Description
Describe your environment:
Relevant environment settings:
-
open-telemetry/opentelemetry-auto-laravel: 1.2.2
-
laravel/octane: v2.5.1
-
laravel/framework: v11.45.1
-
The issue is in the contrib package; so all Laravel versions are affected.
-
Deployment: Both standard PHP-FPM and Laravel Octane deployments are affected
Steps to reproduce
- Set up Laravel application with OpenTelemetry auto-instrumentation enabled
- Create terminable middleware that performs database operations or other traced operations:
class ExampleTerminableMiddleware
{
public function handle($request, Closure $next)
{
return $next($request);
}
public function terminate($request, $response)
{
// This database query will not have correct trace parent
User::count(); // or any other database operation
}
}
- Register the middleware and make a request to trigger it
- Observe the generated traces
What is the expected behavior?
Database queries and other instrumented operations executed during request termination (e.g., in terminable middleware's terminate method) should be part of the same trace as the main request, with proper parent-child span relationships.
What is the actual behavior?
Spans generated during request termination appear as root spans without the correct trace parent, breaking the trace continuity. This happens because the current auto-instrumentation only hooks into the HttpKernel's handle method in open-telemetry/opentelemetry-auto-laravel/src/Hooks/Illuminate/Contracts/Http/Kernel.php, but doesn't encompass the kernel's termination phase.
Additional context
The issue stems from Laravel's request lifecycle having two phases:
- Handle phase: Processing the request and generating response (currently instrumented)
- Termination phase: Running terminable middleware & other terminations after response is sent (not instrumented)
The challenge is that the ideal hook point varies by deployment method:
-
PHP-FPM deployments:
-
laravel/framework/src/Illuminate/Foundation/Application.php:1216 HandleRequest method encompasses both phases
-
Laravel Octane deployments: vendor/laravel/octane/src/Worker.php:63 handle method encompasses both phases (through ApplicationGateway)
Simply hooking the kernel's handle method misses the termination phase in both deployment scenarios. A solution would need to either:
-
Hook into the termination phase separately while maintaining trace context
-
Hook at the application level differently for each deployment type
-
Find a unified hook point that covers the complete request lifecycle across deployments (I didn't find one)
This affects observability for applications using terminable middleware for logging, cleanup tasks, or background job dispatching.
Tip: React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with open-telemetry/opentelemetry-auto-laravel/src/Hooks/Illuminate/Contracts/Http/Kernel.php and compare its hook with the lifecycle entry points in Application.php:1216 and Octane Worker.php:63-77. Trace how the handle and termination phases run in PHP-FPM and Octane. Done means termination-phase database or other instrumented spans retain the request trace parent in both deployment modes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- observability
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100