Laravel: tracing Queues (+ hook refactoring) (#250)

* Laravel: start of QueueWatcher.

* Laravel: PR feedback.

* Laravel: moved additional attributes from event into span.

* Laravel: moved propagation to root of message.

Refs:
https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/#context-propagation
https://w3c.github.io/trace-context-mqtt/#json-payload

* Laravel: experimenting with hooking \Illuminate\Contracts\Queue\Queue.

* Laravel: added queue context propagation via hook.

* Update src/Instrumentation/Laravel/src/Hooks/Queue.php

* Laravel: fix post-hook return. Thanks @brettmc

* Laravel: message processing on the consumer side.

* Laravel: refining queue hooks.

* Laravel: removed the QueueWatcher in favour of hook.

* Laravel: hook restructuring.

* Laravel: moved ServeCommand hook.

* Laravel: hook SyncQueue.

* Laravel: moved main Application hook.

* Laravel: queue cleanup.

* Laravel: test queue tracing.

* Laravel: SyncQueue hook linting.

* Laravel: rebuilt docker image and newer otel-instrumentation fixed this.

* Laravel: update QueueTest.

* Laravel: hook Queue bulk & later.

* Laravel: added estimate delivery_timestamp when passed to Queue->later().

* Laravel: fixing psalm errors.

* Laravel: fixing phpstan errors.

* Laravel: refactoring QueueTest.

* Laravel: added Queue->later tests.

* Laravel: fix Queue->later tests.

* Laravel: added beanstalk message system detection.

* Laravel: added bulk message dispatch test.

* Laravel: added redis connection test.

* Laravel: record a span if a job is received from the queue.

* Laravel: PR feedback to address closing incorrect span.

* Laravel: PR feedback - change confusing ClockInterface mock.

* Laravel: prefer stable dependencies with lowest package compat.

* Laravel: fix dependencies for use with prefer-lowest.

* Laravel: fix lowest dependencies.

* Laravel: fix watcher PhanTypeArraySuspicious warnings.

* Laravel: removed ClockInterface usage to avoid dependency on SDK.

* Laravel: more fixes for phan.

* Laravel: remove erroneous Context destroy usage.

* Laravel: added interface LaravelHook.

* Laravel: suppress psalm warning.

* Laravel: moved Console/Kernel/Command hooks.

* Laravel: export-ignore /.phan.

* Laravel: explicitly list support for Laravel versions 6 to 11.

* Laravel: moved Http Kernel hooks.

* Laravel: consistent test naming.

* Laravel: test dropped empty queue receives.

Author: ChrisLightfootWild

.gitattributes

@@ -5,6 +5,7 @@
 
 /.gitattributes export-ignore
 /.gitignore export-ignore
+/.phan export-ignore
 /.php-cs-fixer.php export-ignore
 /phpstan.neon.dist export-ignore
 /phpunit.xml.dist export-ignore

.php-cs-fixer.php

@@ -40,4 +40,3 @@
     ])
     ->setRiskyAllowed(true)
     ->setFinder($finder);
-

composer.json

@@ -7,21 +7,21 @@
   "readme": "./README.md",
   "license": "Apache-2.0",
   "minimum-stability": "dev",
+  "prefer-stable": true,
   "require": {
     "php": "^8.0",
     "ext-json": "*",
     "ext-opentelemetry": "*",
-    "laravel/framework": ">=6.0",
+    "laravel/framework": "^6.0 || ^7.0 || ^8.0 || ^9.0 || ^10.0 || ^11.0",
     "open-telemetry/api": "^1.0",
-    "open-telemetry/sem-conv": "^1.23"
+    "open-telemetry/sem-conv": "^1.24"
   },
   "require-dev": {
-    "friendsofphp/php-cs-fixer": "^3",
+    "friendsofphp/php-cs-fixer": "^3.50",
     "guzzlehttp/guzzle": "*",
-    "laravel/tinker": "*",
     "nunomaduro/collision": "*",
     "open-telemetry/sdk": "^1.0",
-    "orchestra/testbench": ">=4.0",
+    "orchestra/testbench": ">=7.41.3",
     "phan/phan": "^5.0",
     "php-http/mock-client": "*",
     "phpstan/phpstan": "^1.1",

src/ConsoleInstrumentation.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Contrib\Instrumentation\Laravel\Hooks\Illuminate\Console;
+
+use Illuminate\Console\Command as IlluminateCommand;
+use OpenTelemetry\API\Trace\Span;
+use OpenTelemetry\Context\Context;
+use OpenTelemetry\Contrib\Instrumentation\Laravel\Hooks\LaravelHook;
+use OpenTelemetry\Contrib\Instrumentation\Laravel\Hooks\LaravelHookTrait;
+use OpenTelemetry\Contrib\Instrumentation\Laravel\Hooks\PostHookTrait;
+use function OpenTelemetry\Instrumentation\hook;
+use OpenTelemetry\SemConv\TraceAttributes;
+use Throwable;
+
+class Command implements LaravelHook
+{
+    use LaravelHookTrait;
+    use PostHookTrait;
+
+    public function instrument(): void
+    {
+        $this->hookExecute();
+    }
+
+    protected function hookExecute(): bool
+    {
+        return hook(
+            IlluminateCommand::class,
+            'execute',
+            pre: function (IlluminateCommand $command, array $params, string $class, string $function, ?string $filename, ?int $lineno) {
+                /** @psalm-suppress ArgumentTypeCoercion */
+                $builder = $this->instrumentation
+                    ->tracer()
+                    ->spanBuilder(sprintf('Command %s', $command->getName() ?: 'unknown'))
+                    ->setAttribute(TraceAttributes::CODE_FUNCTION, $function)
+                    ->setAttribute(TraceAttributes::CODE_NAMESPACE, $class)
+                    ->setAttribute(TraceAttributes::CODE_FILEPATH, $filename)
+                    ->setAttribute(TraceAttributes::CODE_LINENO, $lineno);
+
+                $parent = Context::getCurrent();
+                $span = $builder->startSpan();
+                Context::storage()->attach($span->storeInContext($parent));
+
+                return $params;
+            },
+            post: function (IlluminateCommand $command, array $params, ?int $exitCode, ?Throwable $exception) {
+                $scope = Context::storage()->scope();
+                if (!$scope) {
+                    return;
+                }
+
+                $span = Span::fromContext($scope->context());
+                $span->addEvent('command finished', [
+                    'exit-code' => $exitCode,
+                ]);
+
+                $this->endSpan($exception);
+            }
+        );
+    }
+}

src/Hooks/Illuminate/Console/Command.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Contrib\Instrumentation\Laravel\Hooks\Illuminate\Contracts\Console;
+
+use Illuminate\Console\Command;
+use Illuminate\Contracts\Console\Kernel as KernelContract;
+use OpenTelemetry\API\Trace\Span;
+use OpenTelemetry\API\Trace\SpanKind;
+use OpenTelemetry\API\Trace\StatusCode;
+use OpenTelemetry\Context\Context;
+use OpenTelemetry\Contrib\Instrumentation\Laravel\Hooks\Illuminate\Queue\AttributesBuilder;
+use OpenTelemetry\Contrib\Instrumentation\Laravel\Hooks\LaravelHook;
+use OpenTelemetry\Contrib\Instrumentation\Laravel\Hooks\LaravelHookTrait;
+use OpenTelemetry\Contrib\Instrumentation\Laravel\Hooks\PostHookTrait;
+use OpenTelemetry\Contrib\Instrumentation\Laravel\LaravelInstrumentation;
+use function OpenTelemetry\Instrumentation\hook;
+use OpenTelemetry\SemConv\TraceAttributes;
+use Throwable;
+
+class Kernel implements LaravelHook
+{
+    use AttributesBuilder;
+    use LaravelHookTrait;
+    use PostHookTrait;
+
+    public function instrument(): void
+    {
+        if (LaravelInstrumentation::shouldTraceCli()) {
+            $this->hookHandle();
+        }
+    }
+
+    private function hookHandle(): bool
+    {
+        return hook(
+            KernelContract::class,
+            'handle',
+            pre: function (KernelContract $kernel, array $params, string $class, string $function, ?string $filename, ?int $lineno) {
+                /** @psalm-suppress ArgumentTypeCoercion */
+                $builder = $this->instrumentation
+                    ->tracer()
+                    ->spanBuilder('Artisan handler')
+                    ->setSpanKind(SpanKind::KIND_PRODUCER)
+                    ->setAttribute(TraceAttributes::CODE_FUNCTION, $function)
+                    ->setAttribute(TraceAttributes::CODE_NAMESPACE, $class)
+                    ->setAttribute(TraceAttributes::CODE_FILEPATH, $filename)
+                    ->setAttribute(TraceAttributes::CODE_LINENO, $lineno);
+
+                $parent = Context::getCurrent();
+                $span = $builder->startSpan();
+                Context::storage()->attach($span->storeInContext($parent));
+
+                return $params;
+            },
+            post: function (KernelContract $kernel, array $params, ?int $exitCode, ?Throwable $exception) {
+                $scope = Context::storage()->scope();
+                if (!$scope) {
+                    return;
+                }
+
+                $span = Span::fromContext($scope->context());
+
+                if ($exitCode !== Command::SUCCESS) {
+                    $span->setStatus(StatusCode::STATUS_ERROR);
+                }
+
+                $this->endSpan($exception);
+            }
+        );
+    }
+}