Propagate Trace Context Level 2 random flag (#1731)

* Propagate Trace Context Level 2 random flag in `TraceContextPropagator`

* Propagate Trace Context Level 2 random flag in SDK `SpanBuilder`

Author: Nevay

src/API/Trace/Propagation/TraceContextPropagator.php

@@ -19,6 +19,7 @@
 use OpenTelemetry\Context\Propagation\PropagationGetterInterface;
 use OpenTelemetry\Context\Propagation\PropagationSetterInterface;
 use OpenTelemetry\Context\Propagation\TextMapPropagatorInterface;
+use function sprintf;
 
 /**
  * TraceContext is a propagator that supports the W3C Trace Context format
@@ -34,7 +35,8 @@ final class TraceContextPropagator implements TextMapPropagatorInterface
 {
     public const TRACEPARENT = 'traceparent';
     public const TRACESTATE = 'tracestate';
-    private const VERSION = '00'; // Currently, only '00' is supported
+    private const VERSION = 0x00; // Currently, only '00' is supported
+    private const SUPPORTED_FLAGS = TraceFlags::SAMPLED | TraceFlags::RANDOM;
 
     public const FIELDS = [
         self::TRACEPARENT,
@@ -72,7 +74,13 @@ public function inject(&$carrier, ?PropagationSetterInterface $setter = null, ?C
         }
 
         // Build and inject the traceparent header
-        $traceparent = self::VERSION . '-' . $spanContext->getTraceId() . '-' . $spanContext->getSpanId() . '-' . ($spanContext->isSampled() ? '01' : '00');
+        $traceparent = sprintf(
+            '%02x-%s-%s-%02x',
+            self::VERSION,
+            $spanContext->getTraceId(),
+            $spanContext->getSpanId(),
+            $spanContext->getTraceFlags() & self::SUPPORTED_FLAGS,
+        );
         $setter->set($carrier, self::TRACEPARENT, $traceparent);
 
         // Build and inject the tracestate header
@@ -128,33 +136,22 @@ private static function extractImpl($carrier, PropagationGetterInterface $getter
         }
 
         // Return invalid if the trace version is not a future version but still has > 4 pieces.
-        $versionIsFuture = hexdec($version) > hexdec(self::VERSION);
+        $versionIsFuture = hexdec($version) > self::VERSION;
         if (count($pieces) > 4 && !$versionIsFuture) {
             return SpanContext::getInvalid();
         }
 
-        // Only the sampled flag is extracted from the traceFlags (00000001)
-        $convertedTraceFlags = hexdec($traceFlags);
-        $isSampled = ($convertedTraceFlags & TraceFlags::SAMPLED) === TraceFlags::SAMPLED;
-
         // Tracestate = 'Vendor1=Value1,...,VendorN=ValueN'
         $rawTracestate = $getter->get($carrier, self::TRACESTATE);
-        if ($rawTracestate !== null) {
-            $tracestate = new TraceState($rawTracestate);
-
-            return SpanContext::createFromRemoteParent(
-                $traceId,
-                $spanId,
-                $isSampled ? TraceFlags::SAMPLED : TraceFlags::DEFAULT,
-                $tracestate
-            );
-        }
+        $tracestate = $rawTracestate !== null
+            ? new TraceState($rawTracestate)
+            : null;
 
-        // Only traceparent header is extracted. No tracestate.
         return SpanContext::createFromRemoteParent(
             $traceId,
             $spanId,
-            $isSampled ? TraceFlags::SAMPLED : TraceFlags::DEFAULT
+            hexdec($traceFlags) & self::SUPPORTED_FLAGS,
+            $tracestate,
         );
     }
 }

src/API/Trace/TraceFlags.php

@@ -7,5 +7,6 @@
 interface TraceFlags
 {
     public const SAMPLED = 0x01;
+    public const RANDOM = 0x02;
     public const DEFAULT = 0x00;
 }

src/SDK/Trace/SpanBuilder.php

@@ -155,10 +155,15 @@ public function startSpan(): API\SpanInterface
         $samplingDecision = $samplingResult->getDecision();
         $samplingResultTraceState = $samplingResult->getTraceState();
 
+        $flags = $parentSpanContext->getTraceFlags() & 0x2;
+        if ($samplingDecision === SamplingResult::RECORD_AND_SAMPLE) {
+            $flags |= API\TraceFlags::SAMPLED;
+        }
+
         $spanContext = API\SpanContext::create(
             $traceId,
             $spanId,
-            SamplingResult::RECORD_AND_SAMPLE === $samplingDecision ? API\TraceFlags::SAMPLED : API\TraceFlags::DEFAULT,
+            $flags,
             $samplingResultTraceState,
         );
 

tests/Unit/API/Trace/Propagation/TraceContextPropagatorTest.php

@@ -288,6 +288,18 @@ public function test_extract_future_version(): void
         );
     }
 
+    public function test_trace_context_level2_random_flag(): void
+    {
+        $traceparent = '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-03';
+
+        $context = $this->traceContextPropagator->extract([TraceContextPropagator::TRACEPARENT => $traceparent]);
+        $this->assertSame(TraceFlags::SAMPLED | TraceFlags::RANDOM, Span::fromContext($context)->getContext()->getTraceFlags());
+
+        $carrier = [];
+        $this->traceContextPropagator->inject($carrier, context: $context);
+        $this->assertSame($traceparent, $carrier[TraceContextPropagator::TRACEPARENT]);
+    }
+
     public function test_invalid_traceparent_version_0xff(): void
     {
         $this->assertInvalid([

tests/Unit/SDK/Trace/SpanBuilderTest.php

@@ -4,8 +4,12 @@
 
 namespace OpenTelemetry\Tests\Unit\SDK\Trace;
 
+use OpenTelemetry\API\Trace\Span;
+use OpenTelemetry\API\Trace\SpanContext;
 use OpenTelemetry\API\Trace\SpanContextInterface;
 use OpenTelemetry\API\Trace\SpanKind;
+use OpenTelemetry\API\Trace\TraceFlags;
+use OpenTelemetry\Context\Context;
 use OpenTelemetry\SDK\Common\Attribute\AttributesFactoryInterface;
 use OpenTelemetry\SDK\Common\Attribute\AttributesInterface;
 use OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScope;
@@ -85,4 +89,17 @@ public function test_start_span(): void
         $this->assertSame(123456, $span->toSpanData()->getStartEpochNanos());
         $this->assertCount(1, $span->toSpanData()->getLinks());
     }
+
+    public function test_start_span_keeps_trace_random_flag(): void
+    {
+        $this->sampler->method('shouldSample')->willReturn(new SamplingResult(SamplingResult::DROP));
+        $this->idGenerator->method('generateSpanId')->willReturn(self::SPAN_ID);
+
+        $parent = SpanContext::create('4bf92f3577b34da6a3ce929d0e0e4736', '00f067aa0ba902b7', TraceFlags::SAMPLED | TraceFlags::RANDOM);
+        $span = $this->builder
+            ->setParent(Span::wrap($parent)->storeInContext(Context::getCurrent()))
+            ->startSpan();
+
+        $this->assertSame(TraceFlags::RANDOM, $span->getContext()->getTraceFlags());
+    }
 }