[Tracer] Adds SpanEvents Support for DD and OTEL

ext/ddtrace.c

@@ -651,6 +651,35 @@ PHP_METHOD(DDTrace_SpanLink, jsonSerialize) {
     RETURN_ARR(array);
 }
 
+/* DDTrace\SpanEvent */
+zend_class_entry *ddtrace_ce_span_event;
+
+PHP_METHOD(DDTrace_SpanEvent, jsonSerialize) {
+    ddtrace_span_event *event = (ddtrace_span_event*)Z_OBJ_P(ZEND_THIS);
+
+    zend_array *array = zend_new_array(3);
+
+    zend_string *name = zend_string_init("name", sizeof("name") - 1, 0);
+    zend_string *timestamp = zend_string_init("time_unix_nano", sizeof("time_unix_nano") - 1, 0);
+
+    Z_TRY_ADDREF(event->property_name);
+    zend_hash_add(array, name, &event->property_name);
+    Z_TRY_ADDREF(event->property_timestamp);
+    zend_hash_add(array, timestamp, &event->property_timestamp);
+
+    zend_string_release(name);
+    zend_string_release(timestamp);
+
+    if (Z_TYPE(event->property_attributes) != IS_NULL && Z_ARRVAL(event->property_attributes)->nNumOfElements > 0) {
+        zend_string *attributes = zend_string_init("attributes", sizeof("attributes") - 1, 0);
+        Z_TRY_ADDREF(event->property_attributes);
+        zend_hash_add(array, attributes, &event->property_attributes);
+        zend_string_release(attributes);
+    }
+
+    RETURN_ARR(array);
+}
+
 static ddtrace_distributed_tracing_result dd_parse_distributed_tracing_headers_function(INTERNAL_FUNCTION_PARAMETERS, bool *success);
 ZEND_METHOD(DDTrace_SpanLink, fromHeaders) {
     bool success;
@@ -1148,6 +1177,7 @@ static PHP_MINIT_FUNCTION(ddtrace) {
     dd_register_fatal_error_ce();
     ddtrace_ce_integration = register_class_DDTrace_Integration();
     ddtrace_ce_span_link = register_class_DDTrace_SpanLink(php_json_serializable_ce);
+    ddtrace_ce_span_event = register_class_DDTrace_SpanEvent(php_json_serializable_ce);
 
     ddtrace_engine_hooks_minit();
 

ext/ddtrace.h

@@ -23,12 +23,14 @@ extern zend_class_entry *ddtrace_ce_span_stack;
 extern zend_class_entry *ddtrace_ce_fatal_error;
 extern zend_class_entry *ddtrace_ce_span_link;
 extern zend_class_entry *ddtrace_ce_integration;
+extern zend_class_entry *ddtrace_ce_span_event;
 
 typedef struct ddtrace_span_ids_t ddtrace_span_ids_t;
 typedef struct ddtrace_span_data ddtrace_span_data;
 typedef struct ddtrace_root_span_data ddtrace_root_span_data;
 typedef struct ddtrace_span_stack ddtrace_span_stack;
 typedef struct ddtrace_span_link ddtrace_span_link;
+typedef struct ddtrace_span_event ddtrace_span_event;
 
 extern datadog_php_sapi ddtrace_active_sapi;
 

ext/ddtrace.stub.php

@@ -23,6 +23,30 @@
      */
     const DBM_PROPAGATION_FULL = UNKNOWN;
 
+    class SpanEvent implements \JsonSerializable {
+        public function __construct(string $name, ?int $timestamp = null, array $attributes = []) {}
+
+        /**
+         * @var string The event name
+         */
+        public string $name;
+
+        /**
+         * @var int The event start time in nanoseconds, if not provided set the current Unix timestamp
+         */
+        public int $timestamp;
+
+        /**
+         * @var string[] $attributes
+         */
+        public array $attributes;
+
+        /**
+         * @return mixed
+         */
+        public function jsonSerialize(): mixed {}
+    }
+
     class SpanLink implements \JsonSerializable {
         /**
          * @var string $traceId A 32-character, lower-case hexadecimal encoded string of the linked trace ID. This field
@@ -132,6 +156,11 @@ class SpanData {
          */
         public array $links = [];
 
+        /**
+         * @var SpanEvent[] $spanEvents An array of span events
+         */
+        public array $events = [];
+
         /**
          * @var string[] $peerServiceSources A sorted list of tag names used to set the `peer.service` tag. If a tag
          * name is added to this field and the tag exists on the span at serialization time, then the value of the tag

ext/serializer.c

@@ -1319,6 +1319,23 @@ static void _serialize_meta(zval *el, ddtrace_span_data *span) {
         EG(exception) = current_exception;
     }
 
+    zend_array *span_events = ddtrace_property_array(&span->property_events);
+    if (zend_hash_num_elements(span_events) > 0) {
+        // Save the current exception, if any, and clear it for php_json_encode_serializable_object not to fail
+        // and zend_call_function to actually call the jsonSerialize method
+        // Restored after span events are serialized
+        zend_object* current_exception = EG(exception);
+        EG(exception) = NULL;
+
+        smart_str buf = {0};
+        _dd_serialize_json(span_events, &buf, 0);
+        add_assoc_str(meta, "events", buf.s);
+
+        // Restore the exception
+        EG(exception) = current_exception;
+    }
+
+
     if (get_DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED()) { // opt-in
         zend_array *peer_service_sources = ddtrace_property_array(&span->property_peer_service_sources);
         if (zend_hash_str_exists(Z_ARRVAL_P(meta), ZEND_STRL("peer.service"))) { // peer.service is already set by the user, honor it

ext/span.h

@@ -55,6 +55,7 @@ typedef union ddtrace_span_properties {
             zval property_id;
         };
         zval property_links;
+        zval property_events;
         zval property_peer_service_sources;
         union {
             union ddtrace_span_properties *parent;
@@ -170,6 +171,18 @@ struct ddtrace_span_link {
     };
 };
 
+struct ddtrace_span_event {
+    union {
+        zend_object std;
+        struct {
+            char object_placeholder[sizeof(zend_object) - sizeof(zval)];
+            zval property_name;
+            zval property_timestamp;
+            zval property_attributes;
+        };
+    };
+};
+
 void ddtrace_init_span_stacks(void);
 void ddtrace_free_span_stacks(bool silent);
 void ddtrace_switch_span_stack(ddtrace_span_stack *target_stack);

src/DDTrace/OpenTelemetry/Context.php

@@ -189,6 +189,12 @@ private static function activateParent(?SpanData $currentSpan): ContextInterface
             $links[] = new SDK\Link($linkSpanContext, Attributes::create($spanLink->attributes));
         }
 
+        // Check for span events
+        $events = [];
+        foreach ($currentSpan->events as $spanEvent) {
+            $events[] = new SDK\Event($spanEvent->name, (int)$spanEvent->timestamp, Attributes::create($spanEvent->attributes ?? []));
+        }
+
         $OTelCurrentSpan = SDK\Span::startSpan(
             $currentSpan,
             API\SpanContext::create($currentTraceId, $currentSpanId, $traceFlags, $traceState), // $context
@@ -201,6 +207,7 @@ private static function activateParent(?SpanData $currentSpan): ContextInterface
             [], // $attributesBuilder
             $links, // $links
             count($links), // $totalRecordedLinks
+            $events, //$events
             false // The span was created using the DD Api
         );
         ObjectKVStore::put($currentSpan, 'otel_span', $OTelCurrentSpan);

src/DDTrace/OpenTelemetry/Span.php

@@ -6,6 +6,7 @@
 
 use DDTrace\SpanData;
 use DDTrace\SpanLink;
+use DDTrace\SpanEvent;
 use DDTrace\Tag;
 use DDTrace\OpenTelemetry\Convention;
 use DDTrace\Util\ObjectKVStore;
@@ -43,6 +44,14 @@ final class Span extends API\Span implements ReadWriteSpanInterface
      */
     private array $links;
 
+    /**
+     * @readonly
+     *
+     * @var list<EventInterface>
+     */
+    private array $events;
+
+
     /** @readonly */
     private int $totalRecordedLinks;
 
@@ -69,6 +78,7 @@ private function __construct(
         ResourceInfo $resource,
         array $links = [],
         int $totalRecordedLinks = 0,
+        array $events = [],
         bool $isRemapped = true
     ) {
         $this->span = $span;
@@ -80,6 +90,7 @@ private function __construct(
         $this->resource = $resource;
         $this->links = $links;
         $this->totalRecordedLinks = $totalRecordedLinks;
+        $this->events = $events;
 
         $this->status = StatusData::unset();
 
@@ -110,6 +121,19 @@ private function __construct(
                 ObjectKVStore::put($spanLink, "link", $link);
                 $span->links[] = $spanLink;
             }
+
+            foreach ($events as $event) {
+                /** @var EventInterface $event */
+
+                $spanEvent = new SpanEvent();
+                $spanEvent->name = $event->getName();
+                $spanEvent->timestamp = $event->getEpochNanos();
+                $spanEvent->attributes = $event->getAttributes()->toArray();
+
+                // Save the event
+                ObjectKVStore::put($spanEvent, "event", $event);
+                $span->events[] = $spanEvent;
+            }
         }
     }
 
@@ -136,6 +160,7 @@ public static function startSpan(
         array $attributes,
         array $links,
         int $totalRecordedLinks,
+        array $events,
         bool $isRemapped = true // Answers the question "Was the span created using the OTel API?"
     ): self {
         self::_setAttributes($span, $attributes);
@@ -156,6 +181,7 @@ public static function startSpan(
             $resource,
             $links,
             $totalRecordedLinks,
+            $events,
             $isRemapped
         );
 
@@ -203,12 +229,13 @@ public function toSpanData(): SpanDataInterface
         $hasEnded = $this->hasEnded();
 
         $this->updateSpanLinks();
+        $this->updateSpanEvents();
 
         return new ImmutableSpan(
             $this,
             $this->getName(),
             $this->links,
-            [], // TODO: Handle Span Events
+            $this->events,
             Attributes::create(array_merge($this->span->meta, $this->span->metrics)),
             0,
             StatusData::create($this->status->getCode(), $this->status->getDescription()),
@@ -475,4 +502,30 @@ private function updateSpanLinks()
         $this->links = $otel;
         $this->totalRecordedLinks = count($otel);
     }
+
+    private function updateSpanEvents()
+    {
+        $datadogSpanEvents = $this->span->events;
+
+        $otel = [];
+        foreach ($datadogSpanEvents as $datadogSpanEvent) {
+            // Check if the event relationship exists
+            $event = ObjectKVStore::get($datadogSpanEvent, "event");
+            if ($event === null) {
+                // Create the event
+                $event = new Event(
+                    $datadogSpanEvent->name,
+                    (int)$datadogSpanEvent->timestamp,
+                    Attributes::create($datadogSpanEvent->attributes ?? [])
+                );
+
+                // Save the event
+                ObjectKVStore::put($datadogSpanEvent, "event", $event);
+            }
+            $otel[] = $event;
+        }
+
+        // Update the events
+        $this->events = $otel;
+    }
 }

src/DDTrace/OpenTelemetry/SpanBuilder.php

@@ -17,6 +17,7 @@
 use OpenTelemetry\SDK\Common\Attribute\AttributesFactory;
 use OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface;
 use OpenTelemetry\SDK\Resource\ResourceInfoFactory;
+use Throwable;
 
 final class SpanBuilder implements API\SpanBuilderInterface
 {
@@ -43,6 +44,9 @@ final class SpanBuilder implements API\SpanBuilderInterface
     /** @var list<LinkInterface> */
     private array $links = [];
 
+    /** @var list<EventInterface> */
+    private array $events = [];
+
     /** @var array */
     private array $attributes;
 
@@ -92,6 +96,38 @@ public function addLink(SpanContextInterface $context, iterable $attributes = []
         return $this;
     }
 
+    public function addEvent(string $name, int $timestamp = null, iterable $attributes = []): SpanBuilderInterface
+    {
+        $attributesArray = Attributes::create($attributes);
+        $nanoTimestamp = ($timestamp !== null && $timestamp < 1e9) ? $timestamp * 1000 : ($timestamp ?? (int)(microtime(true) * 1e9)); // Convert microseconds to nanoseconds if needed
+        $this->events[] = new Event($name, $nanoTimestamp, Attributes::create($attributes));
+        return $this;
+    }
+
+    public function recordException(Throwable $exception, iterable $attributes = []): SpanBuilderInterface
+    {
+        // Standardized exception attributes
+        $exceptionAttributes = [
+            'exception.message' => $attributes['exception.message'] ?? $exception->getMessage(),
+            'exception.type' => $attributes['exception.type'] ?? get_class($exception),
+            'exception.stacktrace' => $attributes['exception.stacktrace'] ?? $exception->getTraceAsString(),
+            'exception.escaped' => false
+        ];
+
+        // Update span metadata based on exception attributes
+        $this->setAttribute(Tag::ERROR_MSG, $exceptionAttributes['exception.message']);
+        $this->setAttribute(Tag::ERROR_TYPE, $exceptionAttributes['exception.type']);
+        $this->setAttribute(Tag::ERROR_STACK, $exceptionAttributes['exception.stacktrace']);
+
+        // Merge additional attributes
+        $allAttributes = array_merge($exceptionAttributes, iterator_to_array($attributes));
+
+        // Record the exception event
+        $this->addEvent('exception', null, $allAttributes);
+
+        return $this;
+    }
+
     /** @inheritDoc */
     public function setAttribute(string $key, $value): API\SpanBuilderInterface
     {
@@ -156,6 +192,7 @@ public function startSpan(): SpanInterface
                 $this->spanKind,
                 Attributes::create($this->attributes),
                 $this->links,
+                $this->events
             );
 
         $span = $span ?? \DDTrace\start_trace_span($this->startEpochNanos);
@@ -204,6 +241,7 @@ public function startSpan(): SpanInterface
             $this->attributes,
             $this->links,
             $this->totalNumberOfLinksAdded,
+            $this->events
         );
     }