feat: Add strict trace continuation support (#5136)

* feat: Add strict trace continuation support

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

* Format code

* Add changelog entry

* Update API surface file for strict trace continuation

Add public API declarations for new org ID and strict trace
continuation methods on Baggage, PropagationContext, and SentryOptions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Address review comments for strict trace continuation

- Make Dsn.orgId final, remove unnecessary setter
- Fix test signatures to use List<String> for baggage headers
- Add strictTraceContinuation and orgId to ExternalOptions and merge()
- Add options to ManifestMetadataReader for Android manifest config
- Use Sentry.getCurrentScopes().getOptions() in legacy fromHeaders overload
- Improve CHANGELOG description with details about new options
- Update API surface file for ExternalOptions changes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix compilation errors after rebase on main

- Add comment to empty catch block in PropagationContext to satisfy -Werror
- Add setOrgId setter to Dsn class (remove final modifier on orgId field) to
  support the existing test for org ID override

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: Move changelog entry to Unreleased section

* Format code

* fix: Address review comments — pass options to PropagationContext, fix OTel overload, add option tests, make Dsn.orgId final

- Remove PropagationContext.fromHeaders overload without SentryOptions; all
  callers now pass options (or null) explicitly instead of relying on
  Sentry.getCurrentScopes()
- Add SentryOptions parameter to the OTel-facing fromHeaders(SentryTraceHeader,
  Baggage, SpanId) overload so OpenTelemetry integrations also check orgId
- Make Dsn.orgId final and remove the setter — orgId is only set during
  DSN parsing in the constructor
- Add tests for strictTraceContinuation and orgId options in
  ExternalOptionsTest, SentryOptionsTest, and ManifestMetadataReaderTest
- Improve CHANGELOG entry with customer-facing description
- Update API declarations (apiDump)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: Add missing 8.34.1 changelog section

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Format code

* fix: Address PR review comments for strict trace continuation

- Remove duplicated org ID check in PropagationContext.fromHeaders, pass
  options through to the single-check overload instead
- Add debug log when trace is not continued in the SentryTraceHeader overload
- Handle empty/blank org ID strings in shouldContinueTrace to avoid
  silently breaking traces
- Update OtelSentrySpanProcessor to use PropagationContext.fromHeaders
  with options for org_id validation
- Rename ExternalOptions property key to enable-strict-trace-continuation
  (matching the enable- prefix convention for newer options)
- Update ExternalOptionsTest to use the new property key
- Add strict-trace-continuation and org-id properties to all 3 Spring
  Boot SentryAutoConfigurationTest modules
- Improve CHANGELOG entry with detailed customer-facing descriptions
  and configuration examples for all options

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Format code

* fix(tracing): Clarify strict org validation debug log

Update the trace-continuation rejection log message to cover all strict org ID validation failures, including missing org IDs, not just mismatches.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(android): Use enabled suffix for strict trace manifest key

Rename the Android manifest option to io.sentry.strict-trace-continuation.enabled to align with existing enabled-style manifest flags.

Update changelog documentation to match the new Android key.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(api): Mark effective org ID helper as internal

Annotate SentryOptions.getEffectiveOrgId with ApiStatus.Internal since it is used as an internal helper for trace propagation org ID resolution.

Co-Authored-By: Claude <noreply@anthropic.com>

* ref(tracing): Extract trace continuation decision into TracingUtils

Move strict trace continuation org-id validation logic to TracingUtils
so it can be reused by tracing entry points.

Update PropagationContext to call the shared helper and add dedicated
TracingUtils tests for strict/non-strict org-id continuation outcomes.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(opentelemetry): Enforce strict continuation in propagators

Apply strict trace continuation checks in all OpenTelemetry propagator
extract paths before creating remote parent span context.

When org-id validation fails, return the original context and ignore
incoming sentry-trace and baggage to keep propagation behavior aligned
with strict continuation requirements.

Add rejection tests for OtelSentryPropagator, deprecated
SentryPropagator, and OpenTelemetryOtlpPropagator.

Co-Authored-By: Claude <noreply@anthropic.com>

* Format code

* fix(tracing): Fix empty orgId bypassing DSN fallback

The getEffectiveOrgId() method only checked orgId != null, allowing
empty strings and whitespace-only values to bypass the DSN fallback
mechanism. This caused empty org IDs to propagate to outgoing baggage
headers as sentry-org_id=, silently breaking trace continuation in
strict mode.

Update getEffectiveOrgId() to trim the orgId value and check if it's
empty after trimming. Empty or blank values now correctly fall back
to the DSN org ID instead of propagating as empty strings.

Add comprehensive test coverage for all edge cases including empty
strings, whitespace-only values, and their impact on baggage
propagation and strict trace continuation.

Co-Authored-By: Claude <noreply@anthropic.com>

* Format code

* ref: Remove redundant trim of already-trimmed effective org ID

getEffectiveOrgId() already guarantees it returns either null or a
trimmed, non-empty string. The defensive trim and empty check in
shouldContinueTrace was dead code that could never change the result.

Co-Authored-By: Claude <noreply@anthropic.com>

* ref(tracing): Revert shouldContinueTrace check in OtelSentrySpanProcessor

The propagator is the correct enforcement point for org ID validation.
By the time the span processor runs, OTel has already created the span
with the remote parent's trace ID. If shouldContinueTrace rejects here,
it creates a fresh PropagationContext with a mismatched trace ID rather
than cleanly rejecting the trace.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(test): Clean up global Sentry state in SentryPropagatorTest

SentryPropagatorTest calls Sentry.init with strict trace continuation
but never closes Sentry afterward. This leaks global state into
SentrySpanProcessorTest where SentryPropagator uses the global
ScopesAdapter and rejects incoming sentry-trace headers under the
leaked strict mode configuration.

Add @AfterTest that calls Sentry.close() to prevent state leakage.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(test): Use mock scopes in propagator strict continuation tests

The strict continuation tests called Sentry.init with strict mode and
org ID configuration, which leaked global state into other tests.
Sentry.close() does not fully reset the global scope options, so
SentrySpanProcessorTest's SentryPropagator (using ScopesAdapter) would
reject incoming sentry-trace headers.

Use the package-private constructor with mock IScopes instead of
relying on global Sentry state for strict continuation validation.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(test): Reset OTel context in propagator test teardown

Sentry.init uses OtelContextScopesStorage which pushes scopes onto the
OTel context via makeCurrent(). The returned pop-token is discarded by
Sentry.init, and OtelContextScopesStorage.close() is a no-op, so
Sentry.close() alone does not restore the OTel context.

Since JUnit reuses the same thread across test classes, stale scopes
from SentryPropagatorTest (with strict continuation enabled) leaked
into SentrySpanProcessorTest via Context.current().

Add Context.root().makeCurrent() after Sentry.close() in all
propagator test teardowns to reset the thread-local OTel context.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(test): Add back test for inject with invalid span

The previous commit replaced the invalid-span inject test with a
no-span-in-context test. These are distinct scenarios: an explicitly
invalid span vs no span at all. Restore the invalid span test and
keep both.

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Sentry Github Bot <bot+github-bot@sentry.io>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Alexander Dinauer <alexander.dinauer@sentry.io>
Co-authored-by: Alexander Dinauer <adinauer@users.noreply.github.com>

Author: 4 people

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ### Features
 
+- Prevent cross-organization trace continuation ([#5136](https://github.com/getsentry/sentry-java/pull/5136))
+  - By default, the SDK now extracts the organization ID from the DSN (e.g. `o123.ingest.sentry.io`) and compares it with the `sentry-org_id` value in incoming baggage headers. When the two differ, the SDK starts a fresh trace instead of continuing the foreign one. This guards against accidentally linking traces across organizations.
+  - New option `enableStrictTraceContinuation` (default `false`): when enabled, both the SDK's org ID **and** the incoming baggage org ID must be present and match for a trace to be continued. Traces with a missing org ID on either side are rejected. Configurable via code (`setStrictTraceContinuation(true)`), `sentry.properties` (`enable-strict-trace-continuation=true`), Android manifest (`io.sentry.strict-trace-continuation.enabled`), or Spring Boot (`sentry.strict-trace-continuation=true`).
+  - New option `orgId`: allows explicitly setting the organization ID for self-hosted and Relay setups where it cannot be extracted from the DSN. Configurable via code (`setOrgId("123")`), `sentry.properties` (`org-id=123`), Android manifest (`io.sentry.org-id`), or Spring Boot (`sentry.org-id=123`).
 - Android: Attachments on the scope will now be synced to native ([#5211](https://github.com/getsentry/sentry-java/pull/5211))
 - Add THIRD_PARTY_NOTICES.md for vendored third-party code, bundled as SENTRY_THIRD_PARTY_NOTICES.md in the sentry JAR under META-INF ([#5186](https://github.com/getsentry/sentry-java/pull/5186))
 

sentry-android-core/src/main/java/io/sentry/android/core/ManifestMetadataReader.java

@@ -167,6 +167,9 @@ final class ManifestMetadataReader {
 
   static final String FEEDBACK_SHOW_BRANDING = "io.sentry.feedback.show-branding";
 
+  static final String STRICT_TRACE_CONTINUATION = "io.sentry.strict-trace-continuation.enabled";
+  static final String ORG_ID = "io.sentry.org-id";
+
   static final String FEEDBACK_USE_SHAKE_GESTURE = "io.sentry.feedback.use-shake-gesture";
 
   static final String SPOTLIGHT_ENABLE = "io.sentry.spotlight.enable";
@@ -667,6 +670,15 @@ static void applyMetadata(
             readBool(
                 metadata, logger, FEEDBACK_USE_SHAKE_GESTURE, feedbackOptions.isUseShakeGesture()));
 
+        options.setStrictTraceContinuation(
+            readBool(
+                metadata, logger, STRICT_TRACE_CONTINUATION, options.isStrictTraceContinuation()));
+
+        final @Nullable String orgId = readString(metadata, logger, ORG_ID, null);
+        if (orgId != null) {
+          options.setOrgId(orgId);
+        }
+
         options.setEnableSpotlight(
             readBool(metadata, logger, SPOTLIGHT_ENABLE, options.isEnableSpotlight()));
 

sentry-android-core/src/test/java/io/sentry/android/core/ManifestMetadataReaderTest.kt

@@ -2461,4 +2461,54 @@ class ManifestMetadataReaderTest {
     // maskAllImages should also add WebView
     assertTrue(fixture.options.screenshot.maskViewClasses.contains("android.webkit.WebView"))
   }
+
+  @Test
+  fun `applyMetadata reads strictTraceContinuation and keeps default value if not found`() {
+    // Arrange
+    val context = fixture.getContext()
+
+    // Act
+    ManifestMetadataReader.applyMetadata(context, fixture.options, fixture.buildInfoProvider)
+
+    // Assert
+    assertFalse(fixture.options.isStrictTraceContinuation)
+  }
+
+  @Test
+  fun `applyMetadata reads strictTraceContinuation to options`() {
+    // Arrange
+    val bundle = bundleOf(ManifestMetadataReader.STRICT_TRACE_CONTINUATION to true)
+    val context = fixture.getContext(metaData = bundle)
+
+    // Act
+    ManifestMetadataReader.applyMetadata(context, fixture.options, fixture.buildInfoProvider)
+
+    // Assert
+    assertTrue(fixture.options.isStrictTraceContinuation)
+  }
+
+  @Test
+  fun `applyMetadata reads orgId and keeps null if not found`() {
+    // Arrange
+    val context = fixture.getContext()
+
+    // Act
+    ManifestMetadataReader.applyMetadata(context, fixture.options, fixture.buildInfoProvider)
+
+    // Assert
+    assertNull(fixture.options.orgId)
+  }
+
+  @Test
+  fun `applyMetadata reads orgId to options`() {
+    // Arrange
+    val bundle = bundleOf(ManifestMetadataReader.ORG_ID to "12345")
+    val context = fixture.getContext(metaData = bundle)
+
+    // Act
+    ManifestMetadataReader.applyMetadata(context, fixture.options, fixture.buildInfoProvider)
+
+    // Assert
+    assertEquals("12345", fixture.options.orgId)
+  }
 }

sentry-opentelemetry/sentry-opentelemetry-core/src/main/java/io/sentry/opentelemetry/OtelSentryPropagator.java

@@ -113,6 +113,14 @@ public <C> Context extract(
 
       final @Nullable String baggageString = getter.get(carrier, BaggageHeader.BAGGAGE_HEADER);
       final Baggage baggage = Baggage.fromHeader(baggageString);
+      if (!TracingUtils.shouldContinueTrace(scopes.getOptions(), baggage)) {
+        scopes
+            .getOptions()
+            .getLogger()
+            .log(
+                SentryLevel.DEBUG, "Not continuing trace due to strict org ID validation failure.");
+        return context;
+      }
       final @NotNull TraceState traceState = TraceState.getDefault();
 
       SpanContext otelSpanContext =

sentry-opentelemetry/sentry-opentelemetry-core/src/main/java/io/sentry/opentelemetry/SentryPropagator.java

@@ -16,6 +16,7 @@
 import io.sentry.SentryLevel;
 import io.sentry.SentryTraceHeader;
 import io.sentry.exception.InvalidSentryTraceHeaderException;
+import io.sentry.util.TracingUtils;
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
@@ -98,6 +99,17 @@ public <C> Context extract(
     try {
       SentryTraceHeader sentryTraceHeader = new SentryTraceHeader(sentryTraceString);
 
+      final @Nullable String baggageString = getter.get(carrier, BaggageHeader.BAGGAGE_HEADER);
+      Baggage baggage = Baggage.fromHeader(baggageString);
+      if (!TracingUtils.shouldContinueTrace(scopes.getOptions(), baggage)) {
+        scopes
+            .getOptions()
+            .getLogger()
+            .log(
+                SentryLevel.DEBUG, "Not continuing trace due to strict org ID validation failure.");
+        return context;
+      }
+
       SpanContext otelSpanContext =
           SpanContext.createFromRemoteParent(
               sentryTraceHeader.getTraceId().toString(),
@@ -107,9 +119,6 @@ public <C> Context extract(
 
       @NotNull
       Context modifiedContext = context.with(SentryOtelKeys.SENTRY_TRACE_KEY, sentryTraceHeader);
-
-      final @Nullable String baggageString = getter.get(carrier, BaggageHeader.BAGGAGE_HEADER);
-      Baggage baggage = Baggage.fromHeader(baggageString);
       modifiedContext = modifiedContext.with(SentryOtelKeys.SENTRY_BAGGAGE_KEY, baggage);
 
       Span wrappedSpan = Span.wrap(otelSpanContext);

sentry-opentelemetry/sentry-opentelemetry-core/src/main/java/io/sentry/opentelemetry/SentrySampler.java

@@ -91,7 +91,8 @@ public SamplingResult shouldSample(
     final @NotNull PropagationContext propagationContext =
         sentryTraceHeader == null
             ? new PropagationContext(new SentryId(traceId), randomSpanId, null, baggage, null)
-            : PropagationContext.fromHeaders(sentryTraceHeader, baggage, randomSpanId);
+            : PropagationContext.fromHeaders(
+                sentryTraceHeader, baggage, randomSpanId, scopes.getOptions());
 
     final @NotNull TransactionContext transactionContext =
         TransactionContext.fromPropagationContext(propagationContext);

sentry-opentelemetry/sentry-opentelemetry-core/src/main/java/io/sentry/opentelemetry/SentrySpanProcessor.java

@@ -127,7 +127,10 @@ public void onStart(final @NotNull Context parentContext, final @NotNull ReadWri
                   new SentryId(traceData.getTraceId()), spanId, null, null, null)
               : TransactionContext.fromPropagationContext(
                   PropagationContext.fromHeaders(
-                      traceData.getSentryTraceHeader(), traceData.getBaggage(), spanId));
+                      traceData.getSentryTraceHeader(),
+                      traceData.getBaggage(),
+                      spanId,
+                      scopes.getOptions()));
       ;
       transactionContext.setName(transactionName);
       transactionContext.setTransactionNameSource(transactionNameSource);

sentry-opentelemetry/sentry-opentelemetry-core/src/test/kotlin/OtelSentryPropagatorTest.kt

@@ -19,6 +19,7 @@ import kotlin.test.AfterTest
 import kotlin.test.BeforeTest
 import kotlin.test.Test
 import kotlin.test.assertEquals
+import kotlin.test.assertFalse
 import kotlin.test.assertNotNull
 import kotlin.test.assertNull
 import kotlin.test.assertSame
@@ -38,6 +39,8 @@ class OtelSentryPropagatorTest {
   @AfterTest
   fun cleanup() {
     spanStorage.clear()
+    Sentry.close()
+    Context.root().makeCurrent()
   }
 
   @Test
@@ -69,6 +72,26 @@ class OtelSentryPropagatorTest {
     assertSame(scopeInContext, scopes)
   }
 
+  @Test
+  fun `ignores incoming headers when strict continuation rejects org id`() {
+    Sentry.init { options ->
+      options.dsn = "https://key@o2.ingest.sentry.io/123"
+      options.isStrictTraceContinuation = true
+    }
+    val propagator = OtelSentryPropagator()
+    val carrier: Map<String, String> =
+      mapOf(
+        "sentry-trace" to "f9118105af4a2d42b4124532cd1065ff-424cffc8f94feeee-1",
+        "baggage" to "sentry-trace_id=f9118105af4a2d42b4124532cd1065ff,sentry-org_id=1",
+      )
+
+    val newContext = propagator.extract(Context.root(), carrier, MapGetter())
+
+    assertFalse(Span.fromContext(newContext).spanContext.isValid)
+    assertNull(newContext.get(SENTRY_TRACE_KEY))
+    assertNull(newContext.get(SENTRY_BAGGAGE_KEY))
+  }
+
   @Test
   fun `uses incoming headers`() {
     val propagator = OtelSentryPropagator()

sentry-opentelemetry/sentry-opentelemetry-core/src/test/kotlin/SentryPropagatorTest.kt

@@ -0,0 +1,48 @@
+package io.sentry.opentelemetry
+
+import io.opentelemetry.api.trace.Span
+import io.opentelemetry.context.Context
+import io.sentry.Sentry
+import io.sentry.opentelemetry.SentryOtelKeys.SENTRY_BAGGAGE_KEY
+import io.sentry.opentelemetry.SentryOtelKeys.SENTRY_TRACE_KEY
+import kotlin.test.AfterTest
+import kotlin.test.BeforeTest
+import kotlin.test.Test
+import kotlin.test.assertFalse
+import kotlin.test.assertNull
+
+class SentryPropagatorTest {
+
+  @BeforeTest
+  fun setup() {
+    Sentry.init("https://key@sentry.io/proj")
+  }
+
+  @AfterTest
+  fun teardown() {
+    Sentry.close()
+    Context.root().makeCurrent()
+  }
+
+  @Suppress("DEPRECATION")
+  @Test
+  fun `ignores incoming headers when strict continuation rejects org id`() {
+    Sentry.init { options ->
+      options.dsn = "https://key@o2.ingest.sentry.io/123"
+      options.isStrictTraceContinuation = true
+    }
+
+    val propagator = SentryPropagator()
+    val carrier: Map<String, String> =
+      mapOf(
+        "sentry-trace" to "f9118105af4a2d42b4124532cd1065ff-424cffc8f94feeee-1",
+        "baggage" to "sentry-trace_id=f9118105af4a2d42b4124532cd1065ff,sentry-org_id=1",
+      )
+
+    val newContext = propagator.extract(Context.root(), carrier, MapGetter())
+
+    assertFalse(Span.fromContext(newContext).spanContext.isValid)
+    assertNull(newContext.get(SENTRY_TRACE_KEY))
+    assertNull(newContext.get(SENTRY_BAGGAGE_KEY))
+  }
+}

sentry-opentelemetry/sentry-opentelemetry-otlp/src/main/java/io/sentry/opentelemetry/otlp/OpenTelemetryOtlpPropagator.java

@@ -18,6 +18,7 @@
 import io.sentry.SentryLevel;
 import io.sentry.SentryTraceHeader;
 import io.sentry.exception.InvalidSentryTraceHeaderException;
+import io.sentry.util.TracingUtils;
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.List;
@@ -87,6 +88,16 @@ public <C> Context extract(
       SentryTraceHeader sentryTraceHeader = new SentryTraceHeader(sentryTraceString);
 
       final @Nullable String baggageString = getter.get(carrier, BaggageHeader.BAGGAGE_HEADER);
+      final @Nullable Baggage baggage =
+          baggageString == null ? null : Baggage.fromHeader(baggageString);
+      if (!TracingUtils.shouldContinueTrace(scopes.getOptions(), baggage)) {
+        scopes
+            .getOptions()
+            .getLogger()
+            .log(
+                SentryLevel.DEBUG, "Not continuing trace due to strict org ID validation failure.");
+        return context;
+      }
       final @NotNull TraceState traceState = TraceState.getDefault();
 
       final @NotNull TraceFlags traceFlags =
@@ -104,9 +115,8 @@ public <C> Context extract(
       Span wrappedSpan = Span.wrap(otelSpanContext);
 
       @NotNull Context modifiedContext = context.with(wrappedSpan);
-      if (baggageString != null) {
-        modifiedContext =
-            modifiedContext.with(SENTRY_BAGGAGE_KEY, Baggage.fromHeader(baggageString));
+      if (baggage != null) {
+        modifiedContext = modifiedContext.with(SENTRY_BAGGAGE_KEY, baggage);
       }
 
       scopes