feat(error-tracking): add ambient trace IDs to exceptions

.changeset/ambient-exception-traces.md

@@ -0,0 +1,5 @@
+---
+"posthog-php": minor
+---
+
+Add the active OpenTelemetry trace and span IDs to captured exception events when the application provides OpenTelemetry.

api/public-api.json

@@ -2041,6 +2041,13 @@
                         }
                     ]
                 },
+                "getTraceProperties": {
+                    "static": true,
+                    "abstract": false,
+                    "final": false,
+                    "returnType": "array",
+                    "parameters": []
+                },
                 "overridePrimaryMechanism": {
                     "static": true,
                     "abstract": false,

composer.json

@@ -23,7 +23,8 @@
 	"require-dev": {
 		"phpunit/phpunit": "^11.0",
 		"squizlabs/php_codesniffer": "^4.0",
-		"ext-zlib": "*"
+		"ext-zlib": "*",
+		"open-telemetry/api": "^1.0"
 	},
 	"autoload": {
 		"psr-4": {

lib/Client.php

@@ -621,7 +621,12 @@ public function captureException(
             return false;
         }
 
+        $traceProperties = array_diff_key(
+            ExceptionPayloadBuilder::getTraceProperties(),
+            $this->getContext()['properties'] ?? []
+        );
         $properties = array_merge(
+            $traceProperties,
             $additionalProperties,
             [
                 '$exception_list' => $exceptionList,

lib/ExceptionCapture.php

@@ -429,7 +429,11 @@ private static function sendExceptionEvent(
                 $properties['$php_error_severity'] = $severity;
             }
 
-            $properties = array_merge($providerContext['properties'], $properties);
+            $properties = array_merge(
+                ExceptionPayloadBuilder::getTraceProperties(),
+                $providerContext['properties'],
+                $properties
+            );
 
             $distinctId = $providerContext['distinctId'];
             if ($distinctId === null) {

lib/ExceptionPayloadBuilder.php

@@ -2,6 +2,8 @@
 
 namespace PostHog;
 
+use OpenTelemetry\API\Trace\Span;
+
 /**
  * Builds PostHog error tracking exception payloads.
  *
@@ -12,6 +14,33 @@ class ExceptionPayloadBuilder
     private const CONTEXT_LINES = 5;
     private const DEFAULT_MAX_FRAMES = 20;
 
+    public static function getTraceProperties(): array
+    {
+        try {
+            if (!class_exists(Span::class)) {
+                return [];
+            }
+
+            $context = Span::getCurrent()->getContext();
+            if (!$context->isValid()) {
+                return [];
+            }
+
+            $traceId = $context->getTraceId();
+            $spanId = $context->getSpanId();
+            if (
+                !preg_match('/^[0-9a-f]{32}$/D', $traceId) || $traceId === str_repeat('0', 32)
+                || !preg_match('/^[0-9a-f]{16}$/D', $spanId) || $spanId === str_repeat('0', 16)
+            ) {
+                return [];
+            }
+
+            return ['$trace_id' => $traceId, '$span_id' => $spanId];
+        } catch (\Throwable $error) {
+            return [];
+        }
+    }
+
     /**
      * Build a parsed exception list from a Throwable or string.
      *