feat: add SpanError details and update Span

Author: AdilAzhari

src/Span/Span.php

@@ -6,6 +6,7 @@
 
 use DateTimeImmutable;
 use LaravelTrace\LaravelTrace\Trace\TraceId;
+use Throwable;
 
 final readonly class Span
 {
@@ -18,6 +19,7 @@ public function __construct(
         public SpanStatus $status,
         public DateTimeImmutable $startedAt,
         public ?DateTimeImmutable $finishedAt = null,
+        public ?SpanError $error = null,
     ) {}
 
     public static function start(
@@ -34,6 +36,37 @@ public static function start(
             type: $type,
             status: SpanStatus::Running,
             startedAt: new DateTimeImmutable,
+            error: null,
+        );
+    }
+
+    public function complete(DateTimeImmutable $finishedAt): self
+    {
+        return new self(
+            id: $this->id,
+            traceId: $this->traceId,
+            parentId: $this->parentId,
+            name: $this->name,
+            type: $this->type,
+            status: SpanStatus::Completed,
+            startedAt: $this->startedAt,
+            finishedAt: $finishedAt,
+            error: null,
+        );
+    }
+
+    public function fail(throwable $exception,DateTimeImmutable $finishedAt): self
+    {
+        return new self(
+            id: $this->id,
+            traceId: $this->traceId,
+            parentId: $this->parentId,
+            name: $this->name,
+            type: $this->type,
+            status: SpanStatus::Failed,
+            startedAt: $this->startedAt,
+            finishedAt: $finishedAt,
+            error: SpanError::fromThrowable($exception),
         );
     }
 }

src/Span/SpanError.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LaravelTrace\LaravelTrace\Span;
+
+use Throwable;
+
+final readonly class SpanError
+{
+    public function __construct(
+        public string $type,
+        public string $message,
+        public ?string $file,
+        public ?int $line,
+    ) {
+    }
+
+    public static function fromThrowable(Throwable $exception): self
+    {
+        return new self(
+            type: $exception::class,
+            message: $exception->getMessage(),
+            file: $exception->getFile(),
+            line: $exception->getLine(),
+        );
+    }
+}

src/Tracing/Tracer.php

@@ -12,6 +12,8 @@
 use LaravelTrace\LaravelTrace\Span\SpanType;
 use LaravelTrace\LaravelTrace\Trace\Trace;
 use LogicException;
+use RuntimeException;
+use Throwable;
 
 final readonly class Tracer implements TracerContract
 {
@@ -84,9 +86,10 @@ public function complete(Span $span): Span
         );
     }
 
-    public function fail(Span $span): Span
+    public function fail(Span $span,Throwable $exception,): Span
     {
         return $span->fail(
+            $exception,
             new DateTimeImmutable,
         );
     }

tests/Unit/Span/SpanErrorTest.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+use LaravelTrace\LaravelTrace\Span\SpanError;
+
+it('creates an error from a throwable', function () {
+    $exception = new RuntimeException(
+        'Payment provider timed out',
+    );
+
+    $error = SpanError::fromThrowable($exception);
+
+    expect($error->type)
+        ->toBe(RuntimeException::class)
+        ->and($error->message)
+        ->toBe('Payment provider timed out')
+        ->and($error->file)
+        ->toBe($exception->getFile())
+        ->and($error->line)
+        ->toBe($exception->getLine());
+});

tests/Unit/Span/SpanTest.php

@@ -82,12 +82,20 @@
 
     $finishedAt = new DateTimeImmutable;
 
-    $failed = $span->fail($finishedAt);
+    $exception = new RuntimeException(
+        'Inventory service failed',
+    );
+
+    $failed = $span->fail($exception,$finishedAt);
 
     expect($failed->status)
         ->toBe(SpanStatus::Failed)
         ->and($failed->finishedAt)
         ->toBe($finishedAt)
-        ->and($span->status)
-        ->toBe(SpanStatus::Running);
+        ->and($failed->error)
+        ->not->toBeNull()
+        ->and($failed->error?->type)
+        ->toBe(RuntimeException::class)
+        ->and($failed->error?->message)
+        ->toBe('Inventory service failed');
 });

tests/Unit/Tracing/SpanScopeTest.php

@@ -3,7 +3,10 @@
 declare(strict_types=1);
 
 use LaravelTrace\LaravelTrace\Context\InMemoryTraceContextStore;
+use LaravelTrace\LaravelTrace\Span\Span;
+use LaravelTrace\LaravelTrace\Span\SpanStatus;
 use LaravelTrace\LaravelTrace\Span\SpanType;
+use LaravelTrace\LaravelTrace\Trace\TraceId;
 use LaravelTrace\LaravelTrace\Tracing\Tracer;
 
 it('restores the previous context when closed', function () {
@@ -32,3 +35,56 @@
     expect($tracer->context())
         ->toBe($parentContext);
 });
+
+it('fails a span and restores the previous context', function () {
+    $store = new InMemoryTraceContextStore();
+    $tracer = new Tracer($store);
+
+    $tracer->start('CreateOrder');
+
+    $parent = $tracer->span(
+        'CreateOrder',
+        SpanType::Action,
+    );
+
+    $parentContext = $tracer->context();
+
+    $child = $tracer->span(
+        'ReserveInventory',
+        SpanType::Action,
+    );
+
+    $exception = new RuntimeException(
+        'Inventory service failed',
+    );
+
+    $failed = $child->fail($exception);
+
+    expect($failed->status)
+        ->toBe(SpanStatus::Failed)
+        ->and($failed->error?->type)
+        ->toBe(RuntimeException::class)
+        ->and($failed->error?->message)
+        ->toBe('Inventory service failed')
+        ->and($tracer->context())
+        ->toBe($parentContext);
+});
+
+it('does not retain an error when completing a span', function () {
+    $traceId = TraceId::generate();
+
+    $span = Span::start(
+        traceId: $traceId,
+        name: 'ReserveInventory',
+        type: SpanType::Action,
+    );
+
+    $completed = $span->complete(
+        new DateTimeImmutable(),
+    );
+
+    expect($completed->status)
+        ->toBe(SpanStatus::Completed)
+        ->and($completed->error)
+        ->toBeNull();
+});