Issue 7869 - Support the new W3C random flag

api/all/src/main/java/io/opentelemetry/api/trace/ImmutableTraceFlags.java

@@ -13,7 +13,10 @@
 final class ImmutableTraceFlags implements TraceFlags {
   private static final ImmutableTraceFlags[] INSTANCES = buildInstances();
   // Bit to represent whether trace is sampled or not.
-  private static final byte SAMPLED_BIT = 0x01;
+  static final byte SAMPLED_BIT = 0x01;
+  // Bit to indicate that the lower 56 bits of the trace id have been randomly generated with
+  // uniform distribution
+  static final byte RANDOM_TRACE_ID_BIT = 0x02;
 
   static final ImmutableTraceFlags DEFAULT = fromByte((byte) 0x00);
   static final ImmutableTraceFlags SAMPLED = fromByte(SAMPLED_BIT);
@@ -55,6 +58,11 @@ public boolean isSampled() {
     return (this.byteRep & SAMPLED_BIT) != 0;
   }
 
+  @Override
+  public boolean isTraceIdRandom() {
+    return (this.byteRep & RANDOM_TRACE_ID_BIT) != 0;
+  }
+
   @Override
   public String asHex() {
     return this.hexRep;

api/all/src/main/java/io/opentelemetry/api/trace/SpanContext.java

@@ -12,9 +12,8 @@
 /**
  * A class that represents a span context. A span context contains the state that must propagate to
  * child {@link Span}s and across process boundaries. It contains the identifiers (a {@link TraceId
- * trace_id} and {@link SpanId span_id}) associated with the {@link Span} and a set of options
- * (currently only whether the context is sampled or not), as well as the {@link TraceState
- * traceState} and the {@link boolean remote} flag.
+ * trace_id} and {@link SpanId span_id}) associated with the {@link Span}, {@link TraceFlags}, as
+ * well as the {@link TraceState traceState} and the {@link boolean remote} flag.
  *
  * <p>Implementations of this interface *must* be immutable and have well-defined value-based
  * equals/hashCode implementations. If an implementation does not strictly conform to these

api/all/src/main/java/io/opentelemetry/api/trace/TraceFlags.java

@@ -76,6 +76,18 @@ static TraceFlags fromByte(byte traceFlagsByte) {
    */
   boolean isSampled();
 
+  /**
+   * Returns {@code true} if the TraceId accompanying this {@link TraceFlags} is known to be
+   * generated by a truly random Id generator, otherwise {@code false}. Providing default
+   * implementation just to maintain compatibility.
+   *
+   * @return {@code true} if the randomTraceId bit is on for this {@link TraceFlags}, otherwise
+   *     {@code false}.
+   */
+  default boolean isTraceIdRandom() {
+    return false;
+  }
+
   /**
    * Returns the lowercase hex (base16) representation of this {@link TraceFlags}.
    *
@@ -89,4 +101,26 @@ static TraceFlags fromByte(byte traceFlagsByte) {
    * @return the byte representation of the {@link TraceFlags}.
    */
   byte asByte();
+
+  /**
+   * Returns an instance of {@link TraceFlags} whose value is the result of a bitwise OR between
+   * this object and the SAMPLED bit. This operation does not modify this object.
+   *
+   * @return a new {@link TraceFlags} object representing {@code this | SAMPLED_BIT}
+   */
+  default TraceFlags withSampledBit() {
+    byte newByte = (byte) (asByte() | ImmutableTraceFlags.SAMPLED_BIT);
+    return ImmutableTraceFlags.fromByte(newByte);
+  }
+
+  /**
+   * Returns an instance of {@link TraceFlags} whose value is the result of a bitwise OR between
+   * this object and the RANDOM_TRACE_ID bit. This operation does not modify this object.
+   *
+   * @return a new {@link TraceFlags} object representing {@code this | RANDOM_TRACE_ID_BIT}
+   */
+  default TraceFlags withRandomTraceIdBit() {
+    byte newByte = (byte) (asByte() | ImmutableTraceFlags.RANDOM_TRACE_ID_BIT);
+    return ImmutableTraceFlags.fromByte(newByte);
+  }
 }

api/all/src/test/java/io/opentelemetry/api/trace/TraceFlagsTest.java

@@ -15,17 +15,41 @@ class TraceFlagsTest {
   @Test
   void defaultInstances() {
     assertThat(TraceFlags.getDefault().asHex()).isEqualTo("00");
-    assertThat(TraceFlags.getSampled().asHex()).isEqualTo("01");
+    assertThat(TraceFlags.getDefault().withSampledBit().asHex()).isEqualTo("01");
+    assertThat(TraceFlags.getDefault().withRandomTraceIdBit().asHex()).isEqualTo("02");
+    assertThat(TraceFlags.getDefault().withRandomTraceIdBit().withSampledBit().asHex())
+        .isEqualTo("03");
+    assertThat(TraceFlags.getDefault().withSampledBit().withRandomTraceIdBit().asHex())
+        .isEqualTo("03");
+  }
+
+  @Test
+  void idempotency() {
+    assertThat(TraceFlags.getDefault().withRandomTraceIdBit().withRandomTraceIdBit().asHex())
+        .isEqualTo("02");
+    assertThat(TraceFlags.getDefault().withSampledBit().withSampledBit().asHex()).isEqualTo("01");
   }
 
   @Test
   void isSampled() {
     assertThat(TraceFlags.fromByte((byte) 0xff).isSampled()).isTrue();
     assertThat(TraceFlags.fromByte((byte) 0x01).isSampled()).isTrue();
+    assertThat(TraceFlags.fromByte((byte) 0x02).isSampled()).isFalse();
+    assertThat(TraceFlags.fromByte((byte) 0x03).isSampled()).isTrue();
     assertThat(TraceFlags.fromByte((byte) 0x05).isSampled()).isTrue();
     assertThat(TraceFlags.fromByte((byte) 0x00).isSampled()).isFalse();
   }
 
+  @Test
+  void isTraceIdRandom() {
+    assertThat(TraceFlags.fromByte((byte) 0xff).isTraceIdRandom()).isTrue();
+    assertThat(TraceFlags.fromByte((byte) 0x01).isTraceIdRandom()).isFalse();
+    assertThat(TraceFlags.fromByte((byte) 0x02).isTraceIdRandom()).isTrue();
+    assertThat(TraceFlags.fromByte((byte) 0x03).isTraceIdRandom()).isTrue();
+    assertThat(TraceFlags.fromByte((byte) 0x05).isTraceIdRandom()).isFalse();
+    assertThat(TraceFlags.fromByte((byte) 0x00).isTraceIdRandom()).isFalse();
+  }
+
   @Test
   void toFromHex() {
     for (int i = 0; i < 256; i++) {

docs/apidiffs/current_vs_latest/opentelemetry-api.txt

@@ -1,2 +1,6 @@
 Comparing source compatibility of opentelemetry-api-1.59.0-SNAPSHOT.jar against opentelemetry-api-1.58.0.jar
-No changes.
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.trace.TraceFlags  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) boolean isTraceIdRandom()
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.api.trace.TraceFlags withRandomTraceIdBit()
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.api.trace.TraceFlags withSampledBit()

docs/apidiffs/current_vs_latest/opentelemetry-sdk-trace.txt

@@ -1,2 +1,4 @@
 Comparing source compatibility of opentelemetry-sdk-trace-1.59.0-SNAPSHOT.jar against opentelemetry-sdk-trace-1.58.0.jar
-No changes.
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.trace.IdGenerator  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) boolean generatesRandomTraceIds()

sdk/trace/src/main/java/io/opentelemetry/sdk/trace/IdGenerator.java

@@ -38,4 +38,16 @@ static IdGenerator random() {
    * @return a new valid {@code TraceId}.
    */
   String generateTraceId();
+
+  /**
+   * Declares whether TraceIds generated by this IdGenerator have their lower 56 bits uniformly
+   * distributed over the [0..2^56-1]interval, making them compatible with W3C Trace Context Level 2
+   * recommendation @see <a href=
+   * "https://www.w3.org/TR/trace-context-2/#random-trace-id-flag">Random TraceId flag</a>.
+   *
+   * @return true if the generated TraceIds are random
+   */
+  default boolean generatesRandomTraceIds() {
+    return false;
+  }
 }

sdk/trace/src/main/java/io/opentelemetry/sdk/trace/RandomIdGenerator.java

@@ -38,6 +38,11 @@ public String generateTraceId() {
     return TraceId.fromLongs(idHi, idLo);
   }
 
+  @Override
+  public boolean generatesRandomTraceIds() {
+    return true;
+  }
+
   @Override
   public String toString() {
     return "RandomIdGenerator{}";

sdk/trace/src/main/java/io/opentelemetry/sdk/trace/SdkSpanBuilder.java

@@ -16,8 +16,10 @@
 import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.api.trace.SpanBuilder;
 import io.opentelemetry.api.trace.SpanContext;
+import io.opentelemetry.api.trace.SpanId;
 import io.opentelemetry.api.trace.SpanKind;
 import io.opentelemetry.api.trace.TraceFlags;
+import io.opentelemetry.api.trace.TraceId;
 import io.opentelemetry.api.trace.TraceState;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.sdk.common.InstrumentationScopeInfo;
@@ -39,6 +41,7 @@ class SdkSpanBuilder implements SpanBuilder {
   private final InstrumentationScopeInfo instrumentationScopeInfo;
   private final TracerSharedState tracerSharedState;
   private final SpanLimits spanLimits;
+  private final Context rootContextWithRandomTraceIdBit;
 
   @Nullable private Context parent; // null means: Use current context.
   private SpanKind spanKind = SpanKind.INTERNAL;
@@ -56,6 +59,23 @@ class SdkSpanBuilder implements SpanBuilder {
     this.instrumentationScopeInfo = instrumentationScopeInfo;
     this.tracerSharedState = tracerSharedState;
     this.spanLimits = spanLimits;
+    this.rootContextWithRandomTraceIdBit =
+        preparePrimordialContext(
+            Context.root(),
+            TraceFlags.getDefault().withRandomTraceIdBit(),
+            TraceState.getDefault());
+  }
+
+  /*
+   * A primordial context can be passed as the parent context for a root span
+   * if a non-default TraceFlags or TraceState need to be passed to the sampler
+   */
+  private static Context preparePrimordialContext(
+      Context parentContext, TraceFlags traceFlags, TraceState traceState) {
+    SpanContext spanContext =
+        SpanContext.create(TraceId.getInvalid(), SpanId.getInvalid(), traceFlags, traceState);
+    Span span = Span.wrap(spanContext);
+    return span.storeInContext(parentContext);
   }
 
   @Override
@@ -170,14 +190,25 @@ public Span startSpan() {
     Span parentSpan = Span.fromContext(parentContext);
     SpanContext parentSpanContext = parentSpan.getSpanContext();
     String traceId;
+    boolean isTraceIdRandom;
     IdGenerator idGenerator = tracerSharedState.getIdGenerator();
     String spanId = idGenerator.generateSpanId();
+
+    Context parentContextForSampler = parentContext;
     if (!parentSpanContext.isValid()) {
       // New root span.
       traceId = idGenerator.generateTraceId();
+      if (idGenerator.generatesRandomTraceIds()) {
+        isTraceIdRandom = true;
+        // Replace parentContext for sampling with one with RANDOM_TRACE_ID bit set
+        parentContextForSampler = rootContextWithRandomTraceIdBit;
+      } else {
+        isTraceIdRandom = false;
+      }
     } else {
       // New child span.
       traceId = parentSpanContext.getTraceId();
+      isTraceIdRandom = parentSpanContext.getTraceFlags().isTraceIdRandom();
     }
     List<LinkData> currentLinks = links;
     List<LinkData> immutableLinks =
@@ -190,7 +221,12 @@ public Span startSpan() {
         tracerSharedState
             .getSampler()
             .shouldSample(
-                parentContext, traceId, spanName, spanKind, immutableAttributes, immutableLinks);
+                parentContextForSampler,
+                traceId,
+                spanName,
+                spanKind,
+                immutableAttributes,
+                immutableLinks);
     SamplingDecision samplingDecision = samplingResult.getDecision();
 
     TraceState samplingResultTraceState =
@@ -199,7 +235,7 @@ public Span startSpan() {
         ImmutableSpanContext.create(
             traceId,
             spanId,
-            isSampled(samplingDecision) ? TraceFlags.getSampled() : TraceFlags.getDefault(),
+            newTraceFlags(isTraceIdRandom, isSampled(samplingDecision)),
             samplingResultTraceState,
             /* remote= */ false,
             tracerSharedState.isIdGeneratorSafeToSkipIdValidation());
@@ -239,6 +275,17 @@ public Span startSpan() {
         recordEndSpanMetrics);
   }
 
+  private static TraceFlags newTraceFlags(boolean randomTraceId, boolean sampled) {
+    TraceFlags traceFlags = TraceFlags.getDefault();
+    if (randomTraceId) {
+      traceFlags = traceFlags.withRandomTraceIdBit();
+    }
+    if (sampled) {
+      traceFlags = traceFlags.withSampledBit();
+    }
+    return traceFlags;
+  }
+
   private AttributesMap attributes() {
     AttributesMap attributes = this.attributes;
     if (attributes == null) {

sdk/trace/src/test/java/io/opentelemetry/sdk/trace/SdkSpanBuilderTest.java

@@ -902,6 +902,38 @@ void parent_invalidContext() {
     }
   }
 
+  @Test
+  void propagateRandomTraceIdFlag() {
+    Span parent = sdkTracer.spanBuilder(SPAN_NAME).startSpan();
+    assertThat(parent.getSpanContext().getTraceFlags().isTraceIdRandom()).isTrue();
+    try (Scope ignored = parent.makeCurrent()) {
+      Span span = (SdkSpan) sdkTracer.spanBuilder(SPAN_NAME).startSpan();
+      assertThat(span.getSpanContext().getTraceId())
+          .isEqualTo(parent.getSpanContext().getTraceId());
+      assertThat(span.getSpanContext().getTraceFlags().isTraceIdRandom()).isTrue();
+      try (Scope spanScope = span.makeCurrent()) {
+        // Nested span
+        Span nestedSpan = sdkTracer.spanBuilder(SPAN_NAME).startSpan();
+        // check that still the same trace
+        assertThat(nestedSpan.getSpanContext().getTraceId())
+            .isEqualTo(parent.getSpanContext().getTraceId());
+        // check if RandomTraceIdFlag is still there
+        assertThat(nestedSpan.getSpanContext().getTraceFlags().isTraceIdRandom()).isTrue();
+        try (Scope nestedScope = span.makeCurrent()) {
+          Context nestedContext = Context.current();
+          Span currentSpan = Span.fromContext(nestedContext);
+          assertThat(currentSpan.getSpanContext().getTraceFlags().isTraceIdRandom()).isTrue();
+        } finally {
+          nestedSpan.end();
+        }
+      } finally {
+        span.end();
+      }
+    } finally {
+      parent.end();
+    }
+  }
+
   @Test
   void startTimestamp_numeric() {
     SdkSpan span =
@@ -983,7 +1015,7 @@ void spanDataToString() {
             "SpanData\\{spanContext=ImmutableSpanContext\\{"
                 + "traceId=[0-9a-f]{32}, "
                 + "spanId=[0-9a-f]{16}, "
-                + "traceFlags=01, "
+                + "traceFlags=03, "
                 + "traceState=ArrayBasedTraceState\\{entries=\\[]}, remote=false, valid=true}, "
                 + "parentSpanContext=ImmutableSpanContext\\{"
                 + "traceId=00000000000000000000000000000000, "