Add feature flags to spans

adinauer · adinauer · commit 196b3b43229c · 2025-10-23T12:52:32.000+02:00
diff --git a/sentry-opentelemetry/sentry-opentelemetry-bootstrap/api/sentry-opentelemetry-bootstrap.api b/sentry-opentelemetry/sentry-opentelemetry-bootstrap/api/sentry-opentelemetry-bootstrap.api
@@ -43,6 +43,7 @@ public final class io/sentry/opentelemetry/OtelSpanFactory : io/sentry/ISpanFact
 
 public final class io/sentry/opentelemetry/OtelStrongRefSpanWrapper : io/sentry/opentelemetry/IOtelSpanWrapper {
 	public fun <init> (Lio/opentelemetry/api/trace/Span;Lio/sentry/opentelemetry/IOtelSpanWrapper;)V
+	public fun addFeatureFlag (Ljava/lang/String;Ljava/lang/Boolean;)V
 	public fun finish ()V
 	public fun finish (Lio/sentry/SpanStatus;)V
 	public fun finish (Lio/sentry/SpanStatus;Lio/sentry/SentryDate;)V
@@ -96,6 +97,7 @@ public final class io/sentry/opentelemetry/OtelStrongRefSpanWrapper : io/sentry/
 
 public final class io/sentry/opentelemetry/OtelTransactionSpanForwarder : io/sentry/ITransaction {
 	public fun <init> (Lio/sentry/opentelemetry/IOtelSpanWrapper;)V
+	public fun addFeatureFlag (Ljava/lang/String;Ljava/lang/Boolean;)V
 	public fun finish ()V
 	public fun finish (Lio/sentry/SpanStatus;)V
 	public fun finish (Lio/sentry/SpanStatus;Lio/sentry/SentryDate;)V
diff --git a/sentry-opentelemetry/sentry-opentelemetry-bootstrap/src/main/java/io/sentry/opentelemetry/OtelStrongRefSpanWrapper.java b/sentry-opentelemetry/sentry-opentelemetry-bootstrap/src/main/java/io/sentry/opentelemetry/OtelStrongRefSpanWrapper.java
@@ -310,4 +310,9 @@ public void setContext(@Nullable String key, @Nullable Object context) {
   public @Nullable Attributes getOpenTelemetrySpanAttributes() {
     return delegate.getOpenTelemetrySpanAttributes();
   }
+
+  @Override
+  public void addFeatureFlag(final @Nullable String flag, final @Nullable Boolean result) {
+    delegate.addFeatureFlag(flag, result);
+  }
 }
diff --git a/sentry-opentelemetry/sentry-opentelemetry-bootstrap/src/main/java/io/sentry/opentelemetry/OtelTransactionSpanForwarder.java b/sentry-opentelemetry/sentry-opentelemetry-bootstrap/src/main/java/io/sentry/opentelemetry/OtelTransactionSpanForwarder.java
@@ -309,4 +309,9 @@ public void setName(@NotNull String name, @NotNull TransactionNameSource nameSou
     }
     return name;
   }
+
+  @Override
+  public void addFeatureFlag(final @Nullable String flag, final @Nullable Boolean result) {
+    rootSpan.addFeatureFlag(flag, result);
+  }
 }
diff --git a/sentry-opentelemetry/sentry-opentelemetry-core/api/sentry-opentelemetry-core.api b/sentry-opentelemetry/sentry-opentelemetry-core/api/sentry-opentelemetry-core.api
@@ -57,6 +57,7 @@ public final class io/sentry/opentelemetry/OtelSpanUtils {
 
 public final class io/sentry/opentelemetry/OtelSpanWrapper : io/sentry/opentelemetry/IOtelSpanWrapper {
 	public fun <init> (Lio/opentelemetry/sdk/trace/ReadWriteSpan;Lio/sentry/IScopes;Lio/sentry/SentryDate;Lio/sentry/TracesSamplingDecision;Lio/sentry/opentelemetry/IOtelSpanWrapper;Lio/sentry/SpanId;Lio/sentry/Baggage;)V
+	public fun addFeatureFlag (Ljava/lang/String;Ljava/lang/Boolean;)V
 	public fun finish ()V
 	public fun finish (Lio/sentry/SpanStatus;)V
 	public fun finish (Lio/sentry/SpanStatus;Lio/sentry/SentryDate;)V
diff --git a/sentry-opentelemetry/sentry-opentelemetry-core/src/main/java/io/sentry/opentelemetry/OtelSpanWrapper.java b/sentry-opentelemetry/sentry-opentelemetry-core/src/main/java/io/sentry/opentelemetry/OtelSpanWrapper.java
@@ -24,6 +24,8 @@
 import io.sentry.SpanStatus;
 import io.sentry.TraceContext;
 import io.sentry.TracesSamplingDecision;
+import io.sentry.featureflags.IFeatureFlagBuffer;
+import io.sentry.featureflags.SpanFeatureFlagBuffer;
 import io.sentry.protocol.Contexts;
 import io.sentry.protocol.MeasurementValue;
 import io.sentry.protocol.SentryId;
@@ -75,6 +77,8 @@ public final class OtelSpanWrapper implements IOtelSpanWrapper {
 
   private @NotNull Deque<ISentryLifecycleToken> tokensToCleanup = new ArrayDeque<>(1);
 
+  private final @NotNull IFeatureFlagBuffer featureFlags = SpanFeatureFlagBuffer.create();
+
   public OtelSpanWrapper(
       final @NotNull ReadWriteSpan span,
       final @NotNull IScopes scopes,
@@ -505,6 +509,11 @@ public Map<String, MeasurementValue> getMeasurements() {
     return scopes;
   }
 
+  @Override
+  public void addFeatureFlag(final @Nullable String flag, final @Nullable Boolean result) {
+    featureFlags.add(flag, result);
+  }
+
   @Override
   public @NotNull Context storeInContext(Context context) {
     final @Nullable ReadWriteSpan otelSpan = getSpan();
diff --git a/sentry/api/sentry.api b/sentry/api/sentry.api
@@ -1089,6 +1089,7 @@ public abstract interface class io/sentry/ISocketTagger {
 }
 
 public abstract interface class io/sentry/ISpan {
+	public abstract fun addFeatureFlag (Ljava/lang/String;Ljava/lang/Boolean;)V
 	public abstract fun finish ()V
 	public abstract fun finish (Lio/sentry/SpanStatus;)V
 	public abstract fun finish (Lio/sentry/SpanStatus;Lio/sentry/SentryDate;)V
@@ -1779,6 +1780,7 @@ public final class io/sentry/NoOpSocketTagger : io/sentry/ISocketTagger {
 }
 
 public final class io/sentry/NoOpSpan : io/sentry/ISpan {
+	public fun addFeatureFlag (Ljava/lang/String;Ljava/lang/Boolean;)V
 	public fun finish ()V
 	public fun finish (Lio/sentry/SpanStatus;)V
 	public fun finish (Lio/sentry/SpanStatus;Lio/sentry/SentryDate;)V
@@ -1826,6 +1828,7 @@ public final class io/sentry/NoOpSpanFactory : io/sentry/ISpanFactory {
 }
 
 public final class io/sentry/NoOpTransaction : io/sentry/ITransaction {
+	public fun addFeatureFlag (Ljava/lang/String;Ljava/lang/Boolean;)V
 	public fun finish ()V
 	public fun finish (Lio/sentry/SpanStatus;)V
 	public fun finish (Lio/sentry/SpanStatus;Lio/sentry/SentryDate;)V
@@ -3853,6 +3856,7 @@ public final class io/sentry/SentryTraceHeader {
 public final class io/sentry/SentryTracer : io/sentry/ITransaction {
 	public fun <init> (Lio/sentry/TransactionContext;Lio/sentry/IScopes;)V
 	public fun <init> (Lio/sentry/TransactionContext;Lio/sentry/IScopes;Lio/sentry/TransactionOptions;)V
+	public fun addFeatureFlag (Ljava/lang/String;Ljava/lang/Boolean;)V
 	public fun finish ()V
 	public fun finish (Lio/sentry/SpanStatus;)V
 	public fun finish (Lio/sentry/SpanStatus;Lio/sentry/SentryDate;)V
@@ -3993,13 +3997,15 @@ public final class io/sentry/ShutdownHookIntegration : io/sentry/Integration, ja
 
 public final class io/sentry/Span : io/sentry/ISpan {
 	public fun <init> (Lio/sentry/TransactionContext;Lio/sentry/SentryTracer;Lio/sentry/IScopes;Lio/sentry/SpanOptions;)V
+	public fun addFeatureFlag (Ljava/lang/String;Ljava/lang/Boolean;)V
 	public fun finish ()V
 	public fun finish (Lio/sentry/SpanStatus;)V
 	public fun finish (Lio/sentry/SpanStatus;Lio/sentry/SentryDate;)V
 	public fun getContexts ()Lio/sentry/protocol/Contexts;
 	public fun getData ()Ljava/util/Map;
 	public fun getData (Ljava/lang/String;)Ljava/lang/Object;
 	public fun getDescription ()Ljava/lang/String;
+	public fun getFeatureFlagBuffer ()Lio/sentry/featureflags/IFeatureFlagBuffer;
 	public fun getFinishDate ()Lio/sentry/SentryDate;
 	public fun getMeasurements ()Ljava/util/Map;
 	public fun getOperation ()Ljava/lang/String;
@@ -4759,6 +4765,14 @@ public final class io/sentry/featureflags/NoOpFeatureFlagBuffer : io/sentry/feat
 	public static fun getInstance ()Lio/sentry/featureflags/NoOpFeatureFlagBuffer;
 }
 
+public final class io/sentry/featureflags/SpanFeatureFlagBuffer : io/sentry/featureflags/IFeatureFlagBuffer {
+	public fun add (Ljava/lang/String;Ljava/lang/Boolean;)V
+	public fun clone ()Lio/sentry/featureflags/IFeatureFlagBuffer;
+	public synthetic fun clone ()Ljava/lang/Object;
+	public static fun create ()Lio/sentry/featureflags/IFeatureFlagBuffer;
+	public fun getFeatureFlags ()Lio/sentry/protocol/FeatureFlags;
+}
+
 public abstract interface class io/sentry/hints/AbnormalExit {
 	public abstract fun ignoreCurrentThread ()Z
 	public abstract fun mechanism ()Ljava/lang/String;
diff --git a/sentry/src/main/java/io/sentry/CombinedScopeView.java b/sentry/src/main/java/io/sentry/CombinedScopeView.java
@@ -514,6 +514,10 @@ public void setReplayId(@NotNull SentryId replayId) {
   @Override
   public void addFeatureFlag(final @Nullable String flag, final @Nullable Boolean result) {
     getDefaultWriteScope().addFeatureFlag(flag, result);
+    final @Nullable ISpan span = getSpan();
+    if (span != null) {
+      span.addFeatureFlag(flag, result);
+    }
   }
 
   @Override
diff --git a/sentry/src/main/java/io/sentry/ISpan.java b/sentry/src/main/java/io/sentry/ISpan.java
@@ -274,4 +274,6 @@ ISpan startChild(
   @ApiStatus.Internal
   @NotNull
   ISentryLifecycleToken makeCurrent();
+
+  void addFeatureFlag(@Nullable String flag, @Nullable Boolean result);
 }
diff --git a/sentry/src/main/java/io/sentry/NoOpSpan.java b/sentry/src/main/java/io/sentry/NoOpSpan.java
@@ -189,4 +189,7 @@ public void setContext(@Nullable String key, @Nullable Object context) {}
   public @NotNull ISentryLifecycleToken makeCurrent() {
     return NoOpScopesLifecycleToken.getInstance();
   }
+
+  @Override
+  public void addFeatureFlag(final @Nullable String flag, final @Nullable Boolean result) {}
 }
diff --git a/sentry/src/main/java/io/sentry/NoOpTransaction.java b/sentry/src/main/java/io/sentry/NoOpTransaction.java
@@ -251,4 +251,7 @@ public boolean updateEndDate(final @NotNull SentryDate date) {
   public boolean isNoOp() {
     return true;
   }
+
+  @Override
+  public void addFeatureFlag(final @Nullable String flag, final @Nullable Boolean result) {}
 }
diff --git a/sentry/src/main/java/io/sentry/SentryTracer.java b/sentry/src/main/java/io/sentry/SentryTracer.java
@@ -1021,6 +1021,11 @@ public boolean isNoOp() {
     return false;
   }
 
+  @Override
+  public void addFeatureFlag(final @Nullable String flag, final @Nullable Boolean result) {
+    this.root.addFeatureFlag(flag, result);
+  }
+
   private static final class FinishStatus {
     static final FinishStatus NOT_FINISHED = FinishStatus.notFinished();
 
diff --git a/sentry/src/main/java/io/sentry/Span.java b/sentry/src/main/java/io/sentry/Span.java
@@ -1,5 +1,7 @@
 package io.sentry;
 
+import io.sentry.featureflags.IFeatureFlagBuffer;
+import io.sentry.featureflags.SpanFeatureFlagBuffer;
 import io.sentry.protocol.Contexts;
 import io.sentry.protocol.MeasurementValue;
 import io.sentry.protocol.SentryId;
@@ -49,6 +51,8 @@ public final class Span implements ISpan {
 
   private final @NotNull Contexts contexts = new Contexts();
 
+  private final @NotNull IFeatureFlagBuffer featureFlags = SpanFeatureFlagBuffer.create();
+
   Span(
       final @NotNull SentryTracer transaction,
       final @NotNull IScopes scopes,
@@ -458,4 +462,14 @@ private List<Span> getDirectChildren() {
   public @NotNull ISentryLifecycleToken makeCurrent() {
     return NoOpScopesLifecycleToken.getInstance();
   }
+
+  @Override
+  public void addFeatureFlag(final @Nullable String flag, final @Nullable Boolean result) {
+    featureFlags.add(flag, result);
+  }
+
+  @ApiStatus.Internal
+  public @NotNull IFeatureFlagBuffer getFeatureFlagBuffer() {
+    return featureFlags;
+  }
 }
diff --git a/sentry/src/main/java/io/sentry/featureflags/FeatureFlagBuffer.java b/sentry/src/main/java/io/sentry/featureflags/FeatureFlagBuffer.java
@@ -14,6 +14,16 @@
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Feature flag buffer implementation optimized for usage in scopes.
+ *
+ * <ul>
+ *   <li>When full, the oldest entry is evicted
+ *   <li>Updates to existing entries refresh the entry, meaning it'll be dropped last
+ *   <li>Performance of scope cloning is optimized here
+ *   <li>Supports merging across scope types (GLOBAL, ISOLATION, CURRENT)
+ * </ul>
+ */
 @ApiStatus.Internal
 public final class FeatureFlagBuffer implements IFeatureFlagBuffer {
 
diff --git a/sentry/src/main/java/io/sentry/featureflags/SpanFeatureFlagBuffer.java b/sentry/src/main/java/io/sentry/featureflags/SpanFeatureFlagBuffer.java
@@ -0,0 +1,74 @@
+package io.sentry.featureflags;
+
+import io.sentry.ISentryLifecycleToken;
+import io.sentry.protocol.FeatureFlag;
+import io.sentry.protocol.FeatureFlags;
+import io.sentry.util.AutoClosableReentrantLock;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Feature flag buffer implementation optimized for usage in spans.
+ *
+ * <ul>
+ *   <li>When full, new entries are rejected.
+ *   <li>Updates to existing entries are still allowed even if full.
+ *   <li>Lazily initializes its storage to optimize memory consumption.
+ *   <li>Since spans are not cloned, this implementation does not need to optimize for it.
+ * </ul>
+ */
+@ApiStatus.Internal
+public final class SpanFeatureFlagBuffer implements IFeatureFlagBuffer {
+  private static final int MAX_SIZE = 10;
+
+  // lazily initializing the internal storage to reduce memory consumption when not used
+  private @Nullable Map<String, Boolean> flags = null;
+  private final @NotNull AutoClosableReentrantLock lock = new AutoClosableReentrantLock();
+
+  private SpanFeatureFlagBuffer() {}
+
+  @Override
+  public void add(final @Nullable String flag, final @Nullable Boolean result) {
+    if (flag == null || result == null) {
+      return;
+    }
+    try (final @NotNull ISentryLifecycleToken ignored = lock.acquire()) {
+      if (flags == null) {
+        flags = new LinkedHashMap<>(MAX_SIZE);
+      }
+
+      if (flags.size() < MAX_SIZE || flags.containsKey(flag)) {
+        flags.put(flag, result);
+      }
+    }
+  }
+
+  @Override
+  public @Nullable FeatureFlags getFeatureFlags() {
+    try (final @NotNull ISentryLifecycleToken ignored = lock.acquire()) {
+      if (flags == null || flags.isEmpty()) {
+        return null;
+      }
+
+      final List<FeatureFlag> featureFlags = new ArrayList<>(flags.size());
+      for (Map.Entry<String, Boolean> entry : flags.entrySet()) {
+        featureFlags.add(new FeatureFlag(entry.getKey(), entry.getValue()));
+      }
+      return new FeatureFlags(featureFlags);
+    }
+  }
+
+  @Override
+  public @NotNull IFeatureFlagBuffer clone() {
+    return create();
+  }
+
+  public static @NotNull IFeatureFlagBuffer create() {
+    return new SpanFeatureFlagBuffer();
+  }
+}
diff --git a/sentry/src/main/java/io/sentry/protocol/SentrySpan.java b/sentry/src/main/java/io/sentry/protocol/SentrySpan.java
@@ -11,6 +11,7 @@
 import io.sentry.Span;
 import io.sentry.SpanId;
 import io.sentry.SpanStatus;
+import io.sentry.featureflags.IFeatureFlagBuffer;
 import io.sentry.util.CollectionUtils;
 import io.sentry.util.Objects;
 import io.sentry.vendor.gson.stream.JsonToken;
@@ -73,6 +74,13 @@ public SentrySpan(final @NotNull Span span, final @Nullable Map<String, Object>
     // we lose precision here, from potential nanosecond precision down to 10 microsecond precision
     this.startTimestamp = DateUtils.nanosToSeconds(span.getStartDate().nanoTimestamp());
     this.data = data;
+    final @NotNull IFeatureFlagBuffer featureFlagBuffer = span.getFeatureFlagBuffer();
+    final @Nullable FeatureFlags featureFlags = featureFlagBuffer.getFeatureFlags();
+    if (featureFlags != null && data != null) {
+      for (FeatureFlag featureFlag : featureFlags.getValues()) {
+        data.put("flag.evaluation." + featureFlag.getFlag(), featureFlag.getResult());
+      }
+    }
   }
 
   @ApiStatus.Internal
diff --git a/sentry/src/test/java/io/sentry/featureflags/SpanFeatureFlagBufferTest.kt b/sentry/src/test/java/io/sentry/featureflags/SpanFeatureFlagBufferTest.kt

Original file line number	Diff line number	Diff line change
`@@ -310,4 +310,9 @@ public void setContext(@Nullable String key, @Nullable Object context) {`
`310`	`310`	`public @Nullable Attributes getOpenTelemetrySpanAttributes() {`
`311`	`311`	`return delegate.getOpenTelemetrySpanAttributes();`
`312`	`312`	`}`
	`313`	`+`
	`314`	`+ @Override`
	`315`	`+ public void addFeatureFlag(final @Nullable String flag, final @Nullable Boolean result) {`
	`316`	`+ delegate.addFeatureFlag(flag, result);`
	`317`	`+ }`
`313`	`318`	`}`
Original file line number	Diff line number	Diff line change
`@@ -309,4 +309,9 @@ public void setName(@NotNull String name, @NotNull TransactionNameSource nameSou`
`309`	`309`	`}`
`310`	`310`	`return name;`
`311`	`311`	`}`
	`312`	`+`
	`313`	`+ @Override`
	`314`	`+ public void addFeatureFlag(final @Nullable String flag, final @Nullable Boolean result) {`
	`315`	`+ rootSpan.addFeatureFlag(flag, result);`
	`316`	`+ }`
`312`	`317`	`}`
Original file line number	Diff line number	Diff line change
`@@ -274,4 +274,6 @@ ISpan startChild(`
`274`	`274`	`@ApiStatus.Internal`
`275`	`275`	`@NotNull`
`276`	`276`	`ISentryLifecycleToken makeCurrent();`
	`277`	`+`
	`278`	`+ void addFeatureFlag(@Nullable String flag, @Nullable Boolean result);`
`277`	`279`	`}`
Original file line number	Diff line number	Diff line change
`@@ -189,4 +189,7 @@ public void setContext(@Nullable String key, @Nullable Object context) {}`
`189`	`189`	`public @NotNull ISentryLifecycleToken makeCurrent() {`
`190`	`190`	`return NoOpScopesLifecycleToken.getInstance();`
`191`	`191`	`}`
	`192`	`+`
	`193`	`+ @Override`
	`194`	`+ public void addFeatureFlag(final @Nullable String flag, final @Nullable Boolean result) {}`
`192`	`195`	`}`
Original file line number	Diff line number	Diff line change
`@@ -251,4 +251,7 @@ public boolean updateEndDate(final @NotNull SentryDate date) {`
`251`	`251`	`public boolean isNoOp() {`
`252`	`252`	`return true;`
`253`	`253`	`}`
	`254`	`+`
	`255`	`+ @Override`
	`256`	`+ public void addFeatureFlag(final @Nullable String flag, final @Nullable Boolean result) {}`
`254`	`257`	`}`