feat: trace event listener execution and add a global tracing kill switch

Event listener tracing:
- TracingEventDispatcher extends Laravel's Dispatcher and wraps each
  non-wildcard, non-queued listener in EventListenerTracer::trace(),
  recording a `listener` span per invocation (name, completion/failure
  status). Wildcard and queued listeners are left unwrapped, and
  listeners run normally with no tracing overhead when there's no
  active trace.
- Bound as the app's 'events' singleton in the service provider.

Global enabled switch:
- New `laravel-trace.enabled` config key. Tracer checks it in start()
  before establishing a trace context, so downstream consumers
  (DatabaseQueryListener, EventListenerTracer) that already guard on
  `context() === null` naturally no-op everywhere.
- The check reads the live ConfigRepository rather than a boolean
  captured at construction time: Tracer is resolved early via the
  container's 'events' -> TracingEventDispatcher -> EventListenerTracer
  dependency chain, well before a test's config()->set() override (or
  any runtime config change) would take effect against a frozen value.
- TraceRequest middleware now guards its span() call, since context()
  can legitimately be null after a disabled start().

Also folds in and fixes a duplicate test: a stray tests/DatabaseTracingTest.php
had been added at the wrong path (should live under
tests/Feature/Tracing/, where an equivalently-named file already
existed) and imported the concrete Tracing\Tracer class instead of the
Contracts\Tracer interface used everywhere else. Merged its "globally
disabled" case into the existing tests/Feature/Tracing/DatabaseTracingTest.php
instead of keeping two same-named files, and removed the stray one.

Author: AdilAzhari

config/laravel-trace.php

@@ -3,6 +3,7 @@
 declare(strict_types=1);
 
 return [
+    'enabled' => true,
 
     'database' => [
         'enabled' => true,

src/Config/TraceConfig.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LaravelTrace\LaravelTrace\Config;
+
+final readonly class TraceConfig
+{
+    public function __construct(
+        private bool $enabled,
+        private bool $databaseEnabled,
+    ) {}
+
+    public function enabled(): bool
+    {
+        return $this->enabled;
+    }
+
+    public function databaseEnabled(): bool
+    {
+        return $this->databaseEnabled;
+    }
+}

src/Http/Middleware/TraceRequest.php

@@ -32,29 +32,27 @@ public function handle(
             ],
         );
 
-        $span = $this->tracer->span(
-            name: 'http.request',
-            type: SpanType::Http,
-            attributes: [
-                'http.method' => $request->method(),
-                'http.path' => $request->path(),
-            ],
-        );
+        $scope = $this->tracer->context() !== null
+            ? $this->tracer->span(
+                name: 'http.request',
+                type: SpanType::Http,
+            )
+            : null;
 
         try {
             $response = $next($request);
 
-            $span->attributes([
+            $scope?->attributes([
                 'http.status_code' => $response->getStatusCode(),
             ]);
 
-            $span->close();
+            $scope?->close();
 
             $this->tracer->completeTrace($trace);
 
             return $response;
         } catch (Throwable $exception) {
-            $span->fail($exception);
+            $scope?->fail($exception);
 
             $this->tracer->failTrace(
                 trace: $trace,

src/LaravelTraceServiceProvider.php

@@ -4,7 +4,10 @@
 
 namespace LaravelTrace\LaravelTrace;
 
+use Illuminate\Contracts\Config\Repository as ConfigRepository;
 use Illuminate\Contracts\Foundation\Application;
+use Illuminate\Contracts\Queue\Factory as QueueFactoryContract;
+use Illuminate\Contracts\Queue\Queue;
 use Illuminate\Database\Events\QueryExecuted;
 use Illuminate\Support\Facades\Event;
 use Illuminate\Support\ServiceProvider;
@@ -15,9 +18,11 @@
 use LaravelTrace\LaravelTrace\Contracts\Tracer as TracerContract;
 use LaravelTrace\LaravelTrace\Contracts\TraceRecorder;
 use LaravelTrace\LaravelTrace\Tracing\DatabaseQueryListener;
+use LaravelTrace\LaravelTrace\Tracing\EventListenerTracer;
 use LaravelTrace\LaravelTrace\Tracing\InMemorySpanRecorder;
 use LaravelTrace\LaravelTrace\Tracing\InMemoryTraceRecorder;
 use LaravelTrace\LaravelTrace\Tracing\Tracer;
+use LaravelTrace\LaravelTrace\Tracing\TracingEventDispatcher;
 
 class LaravelTraceServiceProvider extends ServiceProvider
 {
@@ -56,6 +61,36 @@ public function register(): void
             ),
         );
 
+        $this->app->singleton(
+            TracerContract::class,
+            function (Application $app): Tracer {
+                return new Tracer(
+                    contextStore: $app->make(TraceContextStore::class),
+                    spanRecorder: $app->make(SpanRecorder::class),
+                    traceRecorder: $app->make(TraceRecorder::class),
+                    config: $app->make(ConfigRepository::class),
+                );
+            },
+        );
+
+        $this->app->singleton(
+            'events',
+            function (Application $app): TracingEventDispatcher {
+                return (new TracingEventDispatcher(
+                    listenerTracer: $app->make(EventListenerTracer::class),
+                    container: $app,
+                ))
+                    ->setQueueResolver(
+                        fn (): Queue => $app->make(QueueFactoryContract::class)->connection(),
+                    )
+                    ->setTransactionManagerResolver(
+                        fn (): mixed => $app->bound('db.transactions')
+                            ? $app->make('db.transactions')
+                            : null,
+                    );
+            },
+        );
+
         $this->app->singleton(
             DatabaseQueryListener::class,
             function (Application $app): DatabaseQueryListener {
@@ -68,17 +103,6 @@ function (Application $app): DatabaseQueryListener {
                 );
             },
         );
-
-        $this->app->singleton(
-            TracerContract::class,
-            function (Application $app): Tracer {
-                return new Tracer(
-                    contextStore: $app->make(TraceContextStore::class),
-                    spanRecorder: $app->make(SpanRecorder::class),
-                    traceRecorder: $app->make(TraceRecorder::class),
-                );
-            },
-        );
     }
 
     /**

src/Tracing/EventListenerTracer.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LaravelTrace\LaravelTrace\Tracing;
+
+use LaravelTrace\LaravelTrace\Contracts\Tracer;
+use LaravelTrace\LaravelTrace\Span\SpanType;
+use Throwable;
+
+final readonly class EventListenerTracer
+{
+    public function __construct(
+        private Tracer $tracer,
+    ) {}
+
+    /**
+     * @param  callable(): mixed  $listener
+     *
+     * @throws Throwable
+     */
+    public function trace(
+        callable $listener,
+        string $name,
+    ): mixed {
+        if ($this->tracer->context() === null) {
+            return $listener();
+        }
+
+        $scope = $this->tracer->span(
+            name: $name,
+            type: SpanType::Listener,
+        );
+
+        try {
+            $result = $listener();
+
+            $scope->close();
+
+            return $result;
+        } catch (Throwable $exception) {
+            $scope->fail($exception);
+
+            throw $exception;
+        }
+    }
+}

src/Tracing/Tracer.php

@@ -5,6 +5,7 @@
 namespace LaravelTrace\LaravelTrace\Tracing;
 
 use DateTimeImmutable;
+use Illuminate\Contracts\Config\Repository as ConfigRepository;
 use LaravelTrace\LaravelTrace\Context\TraceContext;
 use LaravelTrace\LaravelTrace\Contracts\SpanRecorder;
 use LaravelTrace\LaravelTrace\Contracts\TraceContextStore;
@@ -22,6 +23,7 @@ public function __construct(
         private TraceContextStore $contextStore,
         private SpanRecorder $spanRecorder,
         private TraceRecorder $traceRecorder,
+        private ?ConfigRepository $config = null,
     ) {}
 
     /**
@@ -31,15 +33,29 @@ public function start(string $name, array $attributes = []): Trace
     {
         $trace = Trace::start($name, $attributes);
 
-        $this->setContext(
-            new TraceContext(
-                traceId: $trace->id,
-            ),
-        );
+        if ($this->isEnabled()) {
+            $this->setContext(
+                new TraceContext(
+                    traceId: $trace->id,
+                ),
+            );
+        }
 
         return $trace;
     }
 
+    /**
+     * Read live rather than capturing a boolean at construction time: this
+     * class is resolved early via the container's 'events' -> event
+     * dispatcher -> listener tracer dependency chain, before test/runtime
+     * config overrides to 'laravel-trace.enabled' would have taken effect.
+     */
+    private function isEnabled(): bool
+    {
+        return $this->config === null
+            || (bool) $this->config->get('laravel-trace.enabled', true);
+    }
+
     /**
      * @param  array<string, string|int|float|bool|null>  $attributes
      */

src/Tracing/TracingEventDispatcher.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LaravelTrace\LaravelTrace\Tracing;
+
+use Closure;
+use Illuminate\Contracts\Container\Container;
+use Illuminate\Events\Dispatcher;
+
+final class TracingEventDispatcher extends Dispatcher
+{
+    public function __construct(
+        private readonly EventListenerTracer $listenerTracer,
+        ?Container $container = null,
+    ) {
+        parent::__construct($container);
+    }
+
+    /**
+     * @param  Closure|string|array{class-string, string}  $listener
+     */
+    public function makeListener(
+        $listener,
+        $wildcard = false,
+    ): Closure {
+        $callable = parent::makeListener(
+            $listener,
+            $wildcard,
+        );
+
+        if ($wildcard || $this->isQueuedListener($listener)) {
+            return $callable;
+        }
+
+        return function (mixed $event, array $payload) use (
+            $callable,
+            $listener,
+        ) {
+            return $this->listenerTracer->trace(
+                listener: fn () => $callable($event, $payload),
+                name: $this->listenerName($listener),
+            );
+        };
+    }
+
+    /**
+     * @param  Closure|string|array{class-string, string}  $listener
+     */
+    private function isQueuedListener(mixed $listener): bool
+    {
+        $class = match (true) {
+            is_string($listener) => $this->parseClassCallable($listener)[0],
+            is_array($listener) => $listener[0],
+            default => null,
+        };
+
+        if ($class === null) {
+            return false;
+        }
+
+        return $this->handlerShouldBeQueued($class);
+    }
+
+    private function listenerName(mixed $listener): string
+    {
+        if (is_string($listener)) {
+            return 'listener.'.$listener;
+        }
+
+        if (
+            is_array($listener)
+            && isset($listener[0])
+            && is_string($listener[0])
+        ) {
+            return 'listener.'.$listener[0];
+        }
+
+        return 'listener.closure';
+    }
+}

tests/Feature/Tracing/DatabaseTracingTest.php

@@ -16,10 +16,10 @@
 
     $spans = app(InMemorySpanRecorder::class)->all();
 
-    expect($spans)
-        ->toHaveCount(1);
+    $span = collect($spans)->firstWhere('type', SpanType::Database);
 
-    $span = $spans[0];
+    expect($span)
+        ->not->toBeNull();
 
     expect($span->attributes)
         ->toMatchArray([
@@ -53,6 +53,23 @@
 
     DB::select('select 1');
 
-    expect(app(InMemorySpanRecorder::class)->all())
-        ->toBeEmpty();
+    $spans = app(InMemorySpanRecorder::class)->all();
+
+    expect(collect($spans)->firstWhere('type', SpanType::Database))
+        ->toBeNull();
+});
+
+it('does not trace database queries when tracing is globally disabled', function (): void {
+    config()->set('laravel-trace.enabled', false);
+
+    $tracer = app(Tracer::class);
+
+    $tracer->start('DatabaseTest', []);
+
+    DB::select('select 1');
+
+    $spans = app(InMemorySpanRecorder::class)->all();
+
+    expect(collect($spans)->firstWhere('type', SpanType::Database))
+        ->toBeNull();
 });