feat: auto-instrument HTTP requests with a wrapping span and mutable attributes

TraceRequest now opens an http.request span around the whole request
(completing/failing it alongside the trace), and Span/Trace/SpanScope
gain withAttributes()/attributes() so callers can attach data (e.g.
response status code) before a span or trace closes. Database query
tracing takes its enabled flag from config at bind time instead of
reading config() on every query.

Author: AdilAzhari

src/Contracts/Tracer.php

@@ -12,7 +12,7 @@
 
 interface Tracer
 {
-    public function start(string $name): Trace;
+    public function start(string $name, array $attributes): Trace;
 
     public function Span(
         string $name,

src/Http/Middleware/TraceRequest.php

@@ -7,6 +7,7 @@
 use Closure;
 use Illuminate\Http\Request;
 use LaravelTrace\LaravelTrace\Contracts\Tracer;
+use LaravelTrace\LaravelTrace\Span\SpanType;
 use Symfony\Component\HttpFoundation\Response;
 use Throwable;
 
@@ -16,24 +17,50 @@ public function __construct(
         private Tracer $tracer,
     ) {}
 
+    /**
+     * @throws Throwable
+     */
     public function handle(
         Request $request,
         Closure $next,
     ): Response {
         $trace = $this->tracer->start(
-            sprintf(
-                'HTTP %s %s',
-                $request->method(),
-                $request->path(),
-            ),
+            name: 'http.request',
+            attributes: [
+                'http.method' => $request->method(),
+                'http.path' => $request->path(),
+            ],
+        );
+
+        $span = $this->tracer->span(
+            name: 'http.request',
+            type: SpanType::Http,
+            attributes: [
+                'http.method' => $request->method(),
+                'http.path' => $request->path(),
+            ],
         );
 
         try {
             $response = $next($request);
 
-            // Temporary: we'll add trace completion next.
+            $span->attributes([
+                'http.status_code' => $response->getStatusCode(),
+            ]);
+
+            $span->close();
+
+            $this->tracer->completeTrace($trace);
+
             return $response;
         } catch (Throwable $exception) {
+            $span->fail($exception);
+
+            $this->tracer->failTrace(
+                trace: $trace,
+                exception: $exception,
+            );
+
             throw $exception;
         } finally {
             $this->tracer->clearContext();

src/LaravelTraceServiceProvider.php

@@ -55,7 +55,19 @@ public function register(): void
             ),
         );
 
-        $this->app->singleton(DatabaseQueryListener::class);
+        $this->app->singleton(
+            DatabaseQueryListener::class,
+            function ($app): DatabaseQueryListener {
+                return new DatabaseQueryListener(
+                    tracer: $app->make(TracerContract::class),
+                    enabled: (bool) $app->make('config')->get(
+                        'laravel-trace.database.enabled',
+                        true,
+                    ),
+                );
+            },
+        );
+
         $this->app->singleton(
             TracerContract::class,
             function ($app): Tracer {

src/Span/Span.php

@@ -17,7 +17,7 @@ public function __construct(
         public string $name,
         public SpanType $type,
 
-        /** @var array<string, scalar|null> */
+        /** @var array<string, string|int|float|bool|null> */
         public array $attributes,
 
         public SpanStatus $status,
@@ -101,4 +101,26 @@ public static function completed(
             error: null,
         );
     }
+
+    /**
+     * @param array<string, string|int|float|bool|null> $attributes
+     */
+    public function withAttributes(array $attributes): self
+    {
+        return new self(
+            id: $this->id,
+            traceId: $this->traceId,
+            parentId: $this->parentId,
+            name: $this->name,
+            type: $this->type,
+            attributes: [
+                ...$this->attributes,
+                ...$attributes,
+            ],
+            status: $this->status,
+            startedAt: $this->startedAt,
+            finishedAt: $this->finishedAt,
+            error: $this->error,
+        );
+    }
 }

src/Trace/Trace.php

@@ -16,19 +16,22 @@ public function __construct(
         public DateTimeImmutable $startedAt,
         public ?DateTimeImmutable $finishedAt = null,
         public ?TraceError $error = null,
+        /** @var array<string, string|int|float|bool|null> */
+        public array $attributes = [],
     ) {}
 
-    public static function start(string $name): self
+    public static function start(string $name, array $attributes = []): self
     {
         return new self(
             id: TraceId::generate(),
             name: $name,
             status: TraceStatus::Running,
             startedAt: new DateTimeImmutable,
+            attributes: $attributes,
         );
     }
 
-    public function complete(DateTimeImmutable $finishedAt): self
+    public function complete(DateTimeImmutable $finishedAt, array $attributes = []): self
     {
         return new self(
             id: $this->id,
@@ -37,12 +40,14 @@ public function complete(DateTimeImmutable $finishedAt): self
             startedAt: $this->startedAt,
             finishedAt: $finishedAt,
             error: null,
+            attributes: $attributes,
         );
     }
 
     public function fail(
         Throwable $exception,
         DateTimeImmutable $finishedAt,
+        array $attributes = [],
     ): self {
         return new self(
             id: $this->id,
@@ -51,6 +56,23 @@ public function fail(
             startedAt: $this->startedAt,
             finishedAt: $finishedAt,
             error: TraceError::fromThrowable($exception),
+            attributes: $attributes,
+        );
+    }
+
+    public function withAttributes(array $attributes): self
+    {
+        return new self(
+            id: $this->id,
+            name: $this->name,
+            status: $this->status,
+            startedAt: $this->startedAt,
+            finishedAt: $this->finishedAt,
+            error: $this->error,
+            attributes: [
+                ...$this->attributes,
+                ...$attributes,
+            ],
         );
     }
 }

src/Tracing/DatabaseQueryListener.php

@@ -12,11 +12,12 @@
 {
     public function __construct(
         private Tracer $tracer,
+        private bool $enabled,
     ) {}
 
     public function handle(QueryExecuted $event): void
     {
-        if (! config('laravel-trace.database.enabled', true)) {
+        if (! $this->enabled) {
             return;
         }
 

src/Tracing/SpanScope.php

@@ -13,7 +13,7 @@ final class SpanScope
     private bool $closed = false;
 
     public function __construct(
-        private readonly Span $span,
+        private Span $span,
         private readonly TraceContext $previousContext,
         private readonly Tracer $tracer,
     ) {}
@@ -61,4 +61,28 @@ public function fail(Throwable $exception): Span
 
         return $failed;
     }
+
+    /**
+     * @param  array<string, string|int|float|bool|null>  $attributes
+     */
+    public function attributes(array $attributes): self
+    {
+        if ($this->closed) {
+            return $this;
+        }
+
+        $this->span = $this->span->withAttributes($attributes);
+
+        return $this;
+    }
+
+    /**
+     * @param  array<string, string|int|float|bool|null>  $attributes
+     */
+    public function addAttributes(array $attributes): self
+    {
+        $this->span = $this->span->withAttributes($attributes);
+
+        return $this;
+    }
 }

src/Tracing/Tracer.php

@@ -24,9 +24,9 @@ public function __construct(
         private TraceRecorder $traceRecorder,
     ) {}
 
-    public function start(string $name): Trace
+    public function start(string $name, array $attributes = []): Trace
     {
-        $trace = Trace::start($name);
+        $trace = Trace::start($name, $attributes);
 
         $this->setContext(
             new TraceContext(

tests/Feature/Http/Middleware/TraceRequestTest.php

@@ -35,7 +35,7 @@ function () use ($tracer) {
             expect($tracer->context())
                 ->not->toBeNull()
                 ->and($tracer->context()?->spanId)
-                ->toBeNull();
+                ->not->toBeNull();
 
             return new Response('OK');
         },

tests/Feature/Tracing/DatabaseTracingTest.php

@@ -10,7 +10,7 @@
 it('records database query metadata inside an active trace', function (): void {
     $tracer = app(Tracer::class);
 
-    $tracer->start('DatabaseTest');
+    $tracer->start('DatabaseTest', []);
 
     DB::select('select 1');
 
@@ -49,7 +49,7 @@
 
     $tracer = app(Tracer::class);
 
-    $tracer->start('DatabaseTest');
+    $tracer->start('DatabaseTest', []);
 
     DB::select('select 1');