feat: Add strict trace continuation support

giortzisg · giortzisg · commit f4a473e81af8 · 2026-03-02T16:10:30.000+01:00
Extract org ID from DSN host, add strictTraceContinuation and orgId options, propagate sentry-org_id in baggage, and validate incoming traces per the decision matrix. Closes #5128
diff --git a/sentry/src/main/java/io/sentry/Baggage.java b/sentry/src/main/java/io/sentry/Baggage.java
@@ -186,6 +186,7 @@ public static Baggage fromEvent(
     baggage.setPublicKey(options.retrieveParsedDsn().getPublicKey());
     baggage.setRelease(event.getRelease());
     baggage.setEnvironment(event.getEnvironment());
+    baggage.setOrgId(options.getEffectiveOrgId());
     baggage.setTransaction(transaction);
     // we don't persist sample rate
     baggage.setSampleRate(null);
@@ -450,6 +451,16 @@ public void setReplayId(final @Nullable String replayId) {
     set(DSCKeys.REPLAY_ID, replayId);
   }
 
+  @ApiStatus.Internal
+  public @Nullable String getOrgId() {
+    return get(DSCKeys.ORG_ID);
+  }
+
+  @ApiStatus.Internal
+  public void setOrgId(final @Nullable String orgId) {
+    set(DSCKeys.ORG_ID, orgId);
+  }
+
   /**
    * Sets / updates a value, but only if the baggage is still mutable.
    *
@@ -501,6 +512,7 @@ public void setValuesFromTransaction(
     if (replayId != null && !SentryId.EMPTY_ID.equals(replayId)) {
       setReplayId(replayId.toString());
     }
+    setOrgId(sentryOptions.getEffectiveOrgId());
     setSampleRate(sampleRate(samplingDecision));
     setSampled(StringUtils.toString(sampled(samplingDecision)));
     setSampleRand(sampleRand(samplingDecision));
@@ -536,6 +548,7 @@ public void setValuesFromScope(
     if (!SentryId.EMPTY_ID.equals(replayId)) {
       setReplayId(replayId.toString());
     }
+    setOrgId(options.getEffectiveOrgId());
     setTransaction(null);
     setSampleRate(null);
     setSampled(null);
@@ -632,6 +645,7 @@ public static final class DSCKeys {
     public static final String SAMPLE_RAND = "sentry-sample_rand";
     public static final String SAMPLED = "sentry-sampled";
     public static final String REPLAY_ID = "sentry-replay_id";
+    public static final String ORG_ID = "sentry-org_id";
 
     public static final List<String> ALL =
         Arrays.asList(
@@ -644,6 +658,7 @@ public static final class DSCKeys {
             SAMPLE_RATE,
             SAMPLE_RAND,
             SAMPLED,
-            REPLAY_ID);
+            REPLAY_ID,
+            ORG_ID);
   }
 }
diff --git a/sentry/src/main/java/io/sentry/Dsn.java b/sentry/src/main/java/io/sentry/Dsn.java
@@ -2,15 +2,20 @@
 
 import io.sentry.util.Objects;
 import java.net.URI;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 final class Dsn {
+  private static final @NotNull Pattern ORG_ID_PATTERN = Pattern.compile("^o(\\d+)\\.");
+
   private final @NotNull String projectId;
   private final @Nullable String path;
   private final @Nullable String secretKey;
   private final @NotNull String publicKey;
   private final @NotNull URI sentryUri;
+  private @Nullable String orgId;
 
   /*
   / The project ID which the authenticated user is bound to.
@@ -84,8 +89,25 @@ URI getSentryUri() {
       sentryUri =
           new URI(
               scheme, null, uri.getHost(), uri.getPort(), path + "api/" + projectId, null, null);
+
+      // Extract org ID from host (e.g., "o123.ingest.sentry.io" -> "123")
+      final String host = uri.getHost();
+      if (host != null) {
+        final Matcher matcher = ORG_ID_PATTERN.matcher(host);
+        if (matcher.find()) {
+          orgId = matcher.group(1);
+        }
+      }
     } catch (Throwable e) {
       throw new IllegalArgumentException(e);
     }
   }
+
+  public @Nullable String getOrgId() {
+    return orgId;
+  }
+
+  void setOrgId(final @Nullable String orgId) {
+    this.orgId = orgId;
+  }
 }
diff --git a/sentry/src/main/java/io/sentry/PropagationContext.java b/sentry/src/main/java/io/sentry/PropagationContext.java
@@ -23,13 +23,27 @@ public static PropagationContext fromHeaders(
       final @NotNull ILogger logger,
       final @Nullable String sentryTraceHeaderString,
       final @Nullable List<String> baggageHeaderStrings) {
+    return fromHeaders(logger, sentryTraceHeaderString, baggageHeaderStrings, null);
+  }
+
+  public static @NotNull PropagationContext fromHeaders(
+      final @NotNull ILogger logger,
+      final @Nullable String sentryTraceHeaderString,
+      final @Nullable List<String> baggageHeaderStrings,
+      final @Nullable SentryOptions options) {
     if (sentryTraceHeaderString == null) {
       return new PropagationContext();
     }
 
     try {
       final @NotNull SentryTraceHeader traceHeader = new SentryTraceHeader(sentryTraceHeaderString);
       final @NotNull Baggage baggage = Baggage.fromHeader(baggageHeaderStrings, logger);
+
+      if (options != null && !shouldContinueTrace(options, baggage)) {
+        logger.log(SentryLevel.DEBUG, "Not continuing trace due to org ID mismatch.");
+        return new PropagationContext();
+      }
+
       return fromHeaders(traceHeader, baggage, null);
     } catch (InvalidSentryTraceHeaderException e) {
       logger.log(SentryLevel.DEBUG, e, "Failed to parse Sentry trace header: %s", e.getMessage());
@@ -149,4 +163,25 @@ public void setSampled(final @Nullable Boolean sampled) {
     // should never be null since we ensure it in ctor
     return sampleRand == null ? 0.0 : sampleRand;
   }
+
+  static boolean shouldContinueTrace(
+      final @NotNull SentryOptions options, final @Nullable Baggage baggage) {
+    final @Nullable String sdkOrgId = options.getEffectiveOrgId();
+    final @Nullable String baggageOrgId = baggage != null ? baggage.getOrgId() : null;
+
+    // Mismatched org IDs always reject regardless of strict mode
+    if (sdkOrgId != null && baggageOrgId != null && !sdkOrgId.equals(baggageOrgId)) {
+      return false;
+    }
+
+    // In strict mode, both must be present and match (unless both are missing)
+    if (options.isStrictTraceContinuation()) {
+      if (sdkOrgId == null && baggageOrgId == null) {
+        return true;
+      }
+      return sdkOrgId != null && sdkOrgId.equals(baggageOrgId);
+    }
+
+    return true;
+  }
 }
diff --git a/sentry/src/main/java/io/sentry/Scopes.java b/sentry/src/main/java/io/sentry/Scopes.java
@@ -1135,7 +1135,7 @@ public void reportFullyDisplayed() {
       final @Nullable String sentryTrace, final @Nullable List<String> baggageHeaders) {
     @NotNull
     PropagationContext propagationContext =
-        PropagationContext.fromHeaders(getOptions().getLogger(), sentryTrace, baggageHeaders);
+        PropagationContext.fromHeaders(getOptions().getLogger(), sentryTrace, baggageHeaders, getOptions());
     configureScope(
         (scope) -> {
           scope.withPropagationContext(
diff --git a/sentry/src/main/java/io/sentry/SentryOptions.java b/sentry/src/main/java/io/sentry/SentryOptions.java
@@ -427,6 +427,21 @@ public class SentryOptions {
   /** Whether to propagate W3C traceparent HTTP header. */
   private boolean propagateTraceparent = false;
 
+  /**
+   * Controls whether the SDK requires matching org IDs from incoming baggage to continue a trace.
+   * When true, both the SDK's org ID and the incoming baggage org ID must be present and match.
+   * When false, a mismatch between present org IDs will still start a new trace, but missing org
+   * IDs on either side are tolerated.
+   */
+  private boolean strictTraceContinuation = false;
+
+  /**
+   * An optional organization ID. The SDK will try to extract it from the DSN in most cases but you
+   * can provide it explicitly for self-hosted and Relay setups. This value is used for trace
+   * propagation and for features like {@link #strictTraceContinuation}.
+   */
+  private @Nullable String orgId;
+
   /** Proguard UUID. */
   private @Nullable String proguardUuid;
 
@@ -2287,6 +2302,37 @@ public void setPropagateTraceparent(final boolean propagateTraceparent) {
     this.propagateTraceparent = propagateTraceparent;
   }
 
+  public boolean isStrictTraceContinuation() {
+    return strictTraceContinuation;
+  }
+
+  public void setStrictTraceContinuation(final boolean strictTraceContinuation) {
+    this.strictTraceContinuation = strictTraceContinuation;
+  }
+
+  public @Nullable String getOrgId() {
+    return orgId;
+  }
+
+  public void setOrgId(final @Nullable String orgId) {
+    this.orgId = orgId;
+  }
+
+  /**
+   * Returns the effective org ID, preferring the explicit config option over the DSN-parsed value.
+   */
+  public @Nullable String getEffectiveOrgId() {
+    if (orgId != null) {
+      return orgId;
+    }
+    try {
+      final @Nullable String dsnOrgId = retrieveParsedDsn().getOrgId();
+      return dsnOrgId;
+    } catch (Throwable e) {
+      return null;
+    }
+  }
+
   /**
    * Returns a Proguard UUID.
    *
diff --git a/sentry/src/test/java/io/sentry/DsnTest.kt b/sentry/src/test/java/io/sentry/DsnTest.kt
@@ -103,4 +103,36 @@ class DsnTest {
     Dsn("HTTP://publicKey:secretKey@host/path/id")
     Dsn("HTTPS://publicKey:secretKey@host/path/id")
   }
+
+  @Test
+  fun `extracts org id from host`() {
+    val dsn = Dsn("https://key@o123.ingest.sentry.io/456")
+    assertEquals("123", dsn.orgId)
+  }
+
+  @Test
+  fun `extracts single digit org id from host`() {
+    val dsn = Dsn("https://key@o1.ingest.us.sentry.io/456")
+    assertEquals("1", dsn.orgId)
+  }
+
+  @Test
+  fun `returns null org id when host has no org prefix`() {
+    val dsn = Dsn("https://key@sentry.io/456")
+    assertNull(dsn.orgId)
+  }
+
+  @Test
+  fun `returns null org id for non-standard host`() {
+    val dsn = Dsn("http://key@localhost:9000/456")
+    assertNull(dsn.orgId)
+  }
+
+  @Test
+  fun `org id can be overridden via setter`() {
+    val dsn = Dsn("https://key@o123.ingest.sentry.io/456")
+    assertEquals("123", dsn.orgId)
+    dsn.setOrgId("999")
+    assertEquals("999", dsn.orgId)
+  }
 }
diff --git a/sentry/src/test/java/io/sentry/PropagationContextTest.kt b/sentry/src/test/java/io/sentry/PropagationContextTest.kt
@@ -1,7 +1,9 @@
 package io.sentry
 
 import kotlin.test.Test
+import kotlin.test.assertEquals
 import kotlin.test.assertFalse
+import kotlin.test.assertNotEquals
 import kotlin.test.assertNotNull
 import kotlin.test.assertTrue
 
@@ -42,4 +44,99 @@ class PropagationContextTest {
     assertTrue(propagationContext.baggage.isMutable)
     assertFalse(propagationContext.baggage.isShouldFreeze)
   }
+
+  // Decision matrix tests for shouldContinueTrace
+
+  private val incomingTraceId = "bc6d53f15eb88f4320054569b8c553d4"
+  private val sentryTrace = "bc6d53f15eb88f4320054569b8c553d4-b72fa28504b07285-1"
+
+  private fun makeOptions(dsnOrgId: String?, explicitOrgId: String? = null, strict: Boolean = false): SentryOptions {
+    val options = SentryOptions()
+    if (dsnOrgId != null) {
+      options.dsn = "https://key@o$dsnOrgId.ingest.sentry.io/123"
+    } else {
+      options.dsn = "https://key@sentry.io/123"
+    }
+    options.orgId = explicitOrgId
+    options.isStrictTraceContinuation = strict
+    return options
+  }
+
+  private fun makeBaggage(orgId: String?): String {
+    val parts = mutableListOf("sentry-trace_id=$incomingTraceId")
+    if (orgId != null) {
+      parts.add("sentry-org_id=$orgId")
+    }
+    return parts.joinToString(",")
+  }
+
+  @Test
+  fun `strict=false, matching orgs - continues trace`() {
+    val options = makeOptions(dsnOrgId = "1", strict = false)
+    val pc = PropagationContext.fromHeaders(NoOpLogger.getInstance(), sentryTrace, makeBaggage("1"), options)
+    assertEquals(incomingTraceId, pc.traceId.toString())
+  }
+
+  @Test
+  fun `strict=false, baggage missing org - continues trace`() {
+    val options = makeOptions(dsnOrgId = "1", strict = false)
+    val pc = PropagationContext.fromHeaders(NoOpLogger.getInstance(), sentryTrace, makeBaggage(null), options)
+    assertEquals(incomingTraceId, pc.traceId.toString())
+  }
+
+  @Test
+  fun `strict=false, sdk missing org - continues trace`() {
+    val options = makeOptions(dsnOrgId = null, strict = false)
+    val pc = PropagationContext.fromHeaders(NoOpLogger.getInstance(), sentryTrace, makeBaggage("1"), options)
+    assertEquals(incomingTraceId, pc.traceId.toString())
+  }
+
+  @Test
+  fun `strict=false, both missing org - continues trace`() {
+    val options = makeOptions(dsnOrgId = null, strict = false)
+    val pc = PropagationContext.fromHeaders(NoOpLogger.getInstance(), sentryTrace, makeBaggage(null), options)
+    assertEquals(incomingTraceId, pc.traceId.toString())
+  }
+
+  @Test
+  fun `strict=false, mismatched orgs - starts new trace`() {
+    val options = makeOptions(dsnOrgId = "2", strict = false)
+    val pc = PropagationContext.fromHeaders(NoOpLogger.getInstance(), sentryTrace, makeBaggage("1"), options)
+    assertNotEquals(incomingTraceId, pc.traceId.toString())
+  }
+
+  @Test
+  fun `strict=true, matching orgs - continues trace`() {
+    val options = makeOptions(dsnOrgId = "1", strict = true)
+    val pc = PropagationContext.fromHeaders(NoOpLogger.getInstance(), sentryTrace, makeBaggage("1"), options)
+    assertEquals(incomingTraceId, pc.traceId.toString())
+  }
+
+  @Test
+  fun `strict=true, baggage missing org - starts new trace`() {
+    val options = makeOptions(dsnOrgId = "1", strict = true)
+    val pc = PropagationContext.fromHeaders(NoOpLogger.getInstance(), sentryTrace, makeBaggage(null), options)
+    assertNotEquals(incomingTraceId, pc.traceId.toString())
+  }
+
+  @Test
+  fun `strict=true, sdk missing org - starts new trace`() {
+    val options = makeOptions(dsnOrgId = null, strict = true)
+    val pc = PropagationContext.fromHeaders(NoOpLogger.getInstance(), sentryTrace, makeBaggage("1"), options)
+    assertNotEquals(incomingTraceId, pc.traceId.toString())
+  }
+
+  @Test
+  fun `strict=true, both missing org - continues trace`() {
+    val options = makeOptions(dsnOrgId = null, strict = true)
+    val pc = PropagationContext.fromHeaders(NoOpLogger.getInstance(), sentryTrace, makeBaggage(null), options)
+    assertEquals(incomingTraceId, pc.traceId.toString())
+  }
+
+  @Test
+  fun `strict=true, mismatched orgs - starts new trace`() {
+    val options = makeOptions(dsnOrgId = "2", strict = true)
+    val pc = PropagationContext.fromHeaders(NoOpLogger.getInstance(), sentryTrace, makeBaggage("1"), options)
+    assertNotEquals(incomingTraceId, pc.traceId.toString())
+  }
 }
