feat: Implement onEnding interface of Span Processor in Trace SDK (#1785)

* Updated

* Fixed

* nits

* Backport-ed the 2.x Span::end() implementation #1483

Author: jerrytfleung

Trace/ExtendedSpanProcessorInterface.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace;
+
+/**
+ * @experimental
+ */
+interface ExtendedSpanProcessorInterface extends SpanProcessorInterface
+{
+    /**
+     * @see https://github.com/open-telemetry/opentelemetry-specification/blob/v1.51.0/specification/trace/sdk.md#onending
+     */
+    public function onEnding(ReadWriteSpanInterface $span): void;
+}

Trace/Span.php

@@ -26,7 +26,7 @@ final class Span extends API\Span implements ReadWriteSpanInterface
     private array $events = [];
     private int $totalRecordedEvents = 0;
     private StatusDataInterface $status;
-    private int $endEpochNanos = 0;
+    private ?int $endEpochNanos = null;
     private bool $hasEnded = false;
 
     /**
@@ -268,16 +268,20 @@ public function setStatus(string $code, ?string $description = null): self
     #[\Override]
     public function end(?int $endEpochNanos = null): void
     {
-        if ($this->hasEnded) {
+        if ($this->endEpochNanos !== null) {
             return;
         }
 
         $this->endEpochNanos = $endEpochNanos ?? Clock::getDefault()->now();
-        $this->hasEnded = true;
-
-        $this->checkForDroppedElements();
+        $span = clone $this;
+        $this->hasEnded = true; // prevent further modifications to the span by async code
+        if ($this->spanProcessor instanceof ExtendedSpanProcessorInterface) {
+            $this->spanProcessor->onEnding($span);
+        }
+        $span->hasEnded = true;
 
-        $this->spanProcessor->onEnd($this);
+        $this->spanProcessor->onEnd($span);
+        $span->checkForDroppedElements();
     }
 
     /** @inheritDoc */
@@ -317,7 +321,7 @@ public function toSpanData(): SpanDataInterface
             $this->totalRecordedLinks,
             $this->totalRecordedEvents,
             $this->status,
-            $this->endEpochNanos,
+            $this->endEpochNanos ?? 0,
             $this->hasEnded
         );
     }

Trace/SpanProcessor/MultiSpanProcessor.php

@@ -6,6 +6,7 @@
 
 use OpenTelemetry\Context\ContextInterface;
 use OpenTelemetry\SDK\Common\Future\CancellationInterface;
+use OpenTelemetry\SDK\Trace\ExtendedSpanProcessorInterface;
 use OpenTelemetry\SDK\Trace\ReadableSpanInterface;
 use OpenTelemetry\SDK\Trace\ReadWriteSpanInterface;
 use OpenTelemetry\SDK\Trace\SpanProcessorInterface;
@@ -14,7 +15,7 @@
  * Class SpanMultiProcessor is a SpanProcessor that forwards all events to an
  * array of SpanProcessors.
  */
-final class MultiSpanProcessor implements SpanProcessorInterface
+final class MultiSpanProcessor implements ExtendedSpanProcessorInterface
 {
     /** @var list<SpanProcessorInterface> */
     private array $processors = [];
@@ -46,6 +47,17 @@ public function onStart(ReadWriteSpanInterface $span, ContextInterface $parentCo
         }
     }
 
+    /** @inheritDoc */
+    #[\Override]
+    public function onEnding(ReadWriteSpanInterface $span): void
+    {
+        foreach ($this->processors as $processor) {
+            if ($processor instanceof ExtendedSpanProcessorInterface) {
+                $processor->onEnding($span);
+            }
+        }
+    }
+
     /** @inheritDoc */
     #[\Override]
     public function onEnd(ReadableSpanInterface $span): void