feat: Add strict trace continuation support (#1016)

* feat: Add strict trace continuation support

Extract org_id from DSN host (e.g., o1234.ingest.sentry.io -> "1234")
and propagate it as sentry-org_id in outgoing baggage headers. Validate
incoming traces against the SDK's org_id to prevent cross-organization
trace mixing.

New configuration options:
- :org_id - explicit org ID override for self-hosted/Relay setups
- :strict_trace_continuation - when true, both org IDs must be present
  and match to continue a trace (default: false)

Closes #1005

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

* fix: Import TestHelpers in strict trace continuation test

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

* chore: add strict trace continuation tests for baggage propagation

* fix: enhance logging for trace continuation org ID mismatch

* fix: add custom validation for org_id in config

* fix: improve logging for trace continuation org ID validation

* fix: prevent leading comma in baggage when injecting empty string

* refactor: simplify tests

* fix(tests): formatting

* refactor(e2e): improve env var handling in Playwright test suite

- Add `requireEnv()` helper in playwright.config.ts that throws when a
  required env var is missing to make configuration errors explicit
- Use `??=` to set local dev defaults (localhost ports) before validation
  so `npx playwright test` works out of the box without env vars
- Hoist PHOENIX_URL to file scope in tracing.spec.ts with an explicit
  throw, removing the per-describe fallback declarations
- Replace the hardcoded 'http://localhost:4000' URL inside page.evaluate
  with the file-scoped PHOENIX_URL constant

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

* test(e2e): add strict trace continuation integration specs

Add three end-to-end Playwright specs covering the strict trace
continuation feature:

1. Matching org_id in baggage → incoming trace_id is preserved
2. Mismatched org_id in baggage → new trace_id is started
3. No org_id in baggage with strict=false → incoming trace_id is preserved

Supporting changes:
- Pass SENTRY_ORG_ID=123 via the webServer command in playwright.config.ts
  so the Phoenix app starts with an org ID configured
- Read SENTRY_ORG_ID and SENTRY_STRICT_TRACE env vars in
  phoenix_app/config/runtime.exs when SENTRY_E2E_TEST_MODE=true

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

* test(e2e): add strict trace continuation spec for strict=true with no org_id

Adds a 4th E2E spec covering the strict mode path where baggage carries
no sentry-org_id: with strict_trace_continuation=true a new trace must
be started rather than continuing the incoming one.

To enable per-test config toggling without a second server, adds a
PUT /sentry-test-config endpoint to the Phoenix app that calls
Sentry.put_config/2 for an allowlist of keys. A test.afterEach hook
resets strict_trace_continuation back to false after every test so the
setting cannot bleed between specs.

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

* fix(ci): pass SENTRY_ORG_ID=123 when starting Phoenix server in e2e workflow

The strict trace continuation specs require the Phoenix app to have an
org ID configured so that mismatched/missing org IDs in incoming baggage
are correctly rejected. The webServer block in playwright.config.ts
already passes SENTRY_ORG_ID=123, but when SENTRY_E2E_SERVERS_RUNNING=true
that block is skipped and the server is started directly by CI - without
the env var, causing all rejection-path specs to fail.

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

* fix: strip empty sentry-org_id entries before appending SDK org_id to baggage

When incoming baggage contains a sentry-org_id= entry with an empty
value, extract_baggage_org_id/1 correctly returns nil (treating it as
absent). However, ensure_org_id_in_baggage/1 then appended a second
sentry-org_id=<sdk_value> entry, producing a duplicate key. A W3C
baggage parser on a downstream service would pick up the first (empty)
entry and ignore the valid one.

Fix by stripping any empty-valued sentry-org_id entries before appending
the SDK org ID, avoiding duplicate keys entirely.

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

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Peter Solnica <peter@solnica.online>

Author: 3 people

.github/workflows/e2e.yml

@@ -77,7 +77,7 @@ jobs:
         working-directory: test_integrations/phoenix_app
         run: |
           rm -f tmp/sentry_debug_events.log
-          SENTRY_E2E_TEST_MODE=true mix phx.server &
+          SENTRY_E2E_TEST_MODE=true SENTRY_ORG_ID=123 mix phx.server &
           echo $! > /tmp/phoenix.pid
           echo "Phoenix server started with PID $(cat /tmp/phoenix.pid)"
 

lib/sentry/config.ex

@@ -444,6 +444,29 @@ defmodule Sentry.Config do
         ]
       ]
     ],
+    org_id: [
+      type: {:custom, __MODULE__, :__validate_org_id__, []},
+      default: nil,
+      type_doc: "`t:String.t/0` or `nil`",
+      doc: """
+      An explicit organization ID for trace continuation validation. If not set, the SDK
+      will extract it from the DSN host (e.g., `o1234` from `o1234.ingest.sentry.io` gives `"1234"`).
+      This is useful for self-hosted Sentry or Relay setups where the org ID cannot be extracted
+      from the DSN. *Available since 12.1.0*.
+      """
+    ],
+    strict_trace_continuation: [
+      type: :boolean,
+      default: false,
+      doc: """
+      When `true`, both the SDK's org ID and the incoming baggage `sentry-org_id` must be present
+      and match for a trace to be continued. Traces with a missing org ID on either side are rejected
+      and a new trace is started. When `false` (the default), only a mismatch between two present
+      org IDs will cause a new trace to be started. See the
+      [SDK spec](https://develop.sentry.dev/sdk/foundations/trace-propagation/#strict-trace-continuation)
+      for the full decision matrix. *Available since 12.1.0*.
+      """
+    ],
     telemetry_processor_categories: [
       type: {:list, {:in, [:error, :check_in, :transaction, :log]}},
       default: [],
@@ -972,6 +995,29 @@ defmodule Sentry.Config do
   @spec transport_capacity() :: pos_integer()
   def transport_capacity, do: fetch!(:transport_capacity)
 
+  @spec org_id() :: String.t() | nil
+  def org_id, do: get(:org_id)
+
+  @spec strict_trace_continuation?() :: boolean()
+  def strict_trace_continuation?, do: fetch!(:strict_trace_continuation)
+
+  @doc """
+  Returns the effective org ID, preferring the explicit `:org_id` config over the DSN-derived value.
+  """
+  @spec effective_org_id() :: String.t() | nil
+  def effective_org_id do
+    case org_id() do
+      nil ->
+        case dsn() do
+          %Sentry.DSN{org_id: org_id} -> org_id
+          _ -> nil
+        end
+
+      explicit ->
+        explicit
+    end
+  end
+
   @spec telemetry_processor_categories() :: [atom()]
   def telemetry_processor_categories, do: fetch!(:telemetry_processor_categories)
 
@@ -1279,4 +1325,18 @@ defmodule Sentry.Config do
   def __validate_namespace__(other) do
     {:error, "expected :namespace to be a {module, function} tuple, got: #{inspect(other)}"}
   end
+
+  def __validate_org_id__(nil), do: {:ok, nil}
+
+  def __validate_org_id__(value) when is_binary(value) and value != "" do
+    {:ok, value}
+  end
+
+  def __validate_org_id__("") do
+    {:error, "expected :org_id to be a non-empty string or nil, got empty string"}
+  end
+
+  def __validate_org_id__(other) do
+    {:error, "expected :org_id to be a non-empty string or nil, got: #{inspect(other)}"}
+  end
 end

lib/sentry/dsn.ex

@@ -5,14 +5,16 @@ defmodule Sentry.DSN do
           original_dsn: String.t(),
           endpoint_uri: String.t(),
           public_key: String.t(),
-          secret_key: String.t() | nil
+          secret_key: String.t() | nil,
+          org_id: String.t() | nil
         }
 
   defstruct [
     :original_dsn,
     :endpoint_uri,
     :public_key,
-    :secret_key
+    :secret_key,
+    :org_id
   ]
 
   # {PROTOCOL}://{PUBLIC_KEY}:{SECRET_KEY}@{HOST}{PATH}/{PROJECT_ID}
@@ -65,7 +67,8 @@ defmodule Sentry.DSN do
         endpoint_uri: URI.to_string(endpoint_uri),
         public_key: public_key,
         secret_key: secret_key,
-        original_dsn: dsn
+        original_dsn: dsn,
+        org_id: extract_org_id(uri.host)
       }
 
       {:ok, parsed_dsn}
@@ -80,6 +83,16 @@ defmodule Sentry.DSN do
 
   ## Helpers
 
+  # Extract org ID from host (e.g., "o123.ingest.sentry.io" -> "123")
+  defp extract_org_id(host) when is_binary(host) do
+    case Regex.run(~r/^o(\d+)\./, host) do
+      [_, org_id] -> org_id
+      _ -> nil
+    end
+  end
+
+  defp extract_org_id(_host), do: nil
+
   defp pop_project_id(uri_path) do
     path = String.split(uri_path, "/")
     {project_id, path} = List.pop_at(path, -1)

lib/sentry/opentelemetry/propagator.ex

@@ -10,6 +10,7 @@ if Sentry.OpenTelemetry.VersionChecker.tracing_compatible?() do
     import Bitwise
 
     require Record
+    require Logger
     require OpenTelemetry.Tracer, as: Tracer
 
     @behaviour :otel_propagator_text_map
@@ -35,6 +36,7 @@ if Sentry.OpenTelemetry.VersionChecker.tracing_compatible?() do
           carrier = setter.(@sentry_trace_key, sentry_trace_header, carrier)
 
           baggage_value = :otel_ctx.get_value(ctx, @sentry_baggage_ctx_key, :not_found)
+          baggage_value = ensure_org_id_in_baggage(baggage_value)
 
           if is_binary(baggage_value) and baggage_value != :not_found do
             setter.(@sentry_baggage_key, baggage_value, carrier)
@@ -56,19 +58,39 @@ if Sentry.OpenTelemetry.VersionChecker.tracing_compatible?() do
         header when is_binary(header) ->
           case decode_sentry_trace(header) do
             {:ok, {trace_hex, span_hex, sampled}} ->
-              ctx =
-                ctx
-                |> :otel_ctx.set_value(@sentry_trace_ctx_key, {trace_hex, span_hex, sampled})
-                |> maybe_set_baggage(getter.(@sentry_baggage_key, carrier))
+              raw_baggage = getter.(@sentry_baggage_key, carrier)
+
+              if should_continue_trace?(raw_baggage) do
+                ctx =
+                  ctx
+                  |> :otel_ctx.set_value(@sentry_trace_ctx_key, {trace_hex, span_hex, sampled})
+                  |> maybe_set_baggage(raw_baggage)
+
+                trace_id = hex_to_int(trace_hex)
+                span_id = hex_to_int(span_hex)
 
-              trace_id = hex_to_int(trace_hex)
-              span_id = hex_to_int(span_hex)
+                # Create a remote, sampled parent span in the OTEL context.
+                # We will set to "always sample" because Sentry will decide real sampling
+                remote_span_ctx = :otel_tracer.from_remote_span(trace_id, span_id, 1)
 
-              # Create a remote, sampled parent span in the OTEL context.
-              # We will set to "always sample" because Sentry will decide real sampling
-              remote_span_ctx = :otel_tracer.from_remote_span(trace_id, span_id, 1)
+                Tracer.set_current_span(ctx, remote_span_ctx)
+              else
+                sdk_org_id = Sentry.Config.effective_org_id()
+                baggage_org_id = extract_baggage_org_id(raw_baggage)
 
-              Tracer.set_current_span(ctx, remote_span_ctx)
+                reason =
+                  if sdk_org_id != nil and baggage_org_id != nil do
+                    "org ID mismatch"
+                  else
+                    "org ID missing (strict mode)"
+                  end
+
+                Logger.warning(
+                  "[Sentry] Not continuing trace: #{reason} (sdk: #{inspect(sdk_org_id)}, incoming: #{inspect(baggage_org_id)})"
+                )
+
+                ctx
+              end
 
             {:error, _reason} ->
               ctx
@@ -131,5 +153,82 @@ if Sentry.OpenTelemetry.VersionChecker.tracing_compatible?() do
       missing = total_bytes - byte_size(bin)
       if missing > 0, do: :binary.copy(<<0>>, missing) <> bin, else: bin
     end
+
+    # Ensure sentry-org_id is present in the baggage string
+    defp ensure_org_id_in_baggage(baggage) when is_binary(baggage) do
+      org_id = Sentry.Config.effective_org_id()
+
+      if org_id != nil and extract_baggage_org_id(baggage) == nil do
+        # Strip any existing sentry-org_id entries with empty values before appending
+        # to avoid producing duplicate keys (e.g. "sentry-org_id=,sentry-org_id=99").
+        stripped =
+          baggage
+          |> String.split(",")
+          |> Enum.reject(fn entry ->
+            case String.split(String.trim(entry), "=", parts: 2) do
+              ["sentry-org_id", value] -> String.trim(value) == ""
+              _ -> false
+            end
+          end)
+          |> Enum.join(",")
+
+        if stripped == "" do
+          "sentry-org_id=" <> org_id
+        else
+          stripped <> ",sentry-org_id=" <> org_id
+        end
+      else
+        baggage
+      end
+    end
+
+    defp ensure_org_id_in_baggage(_baggage) do
+      case Sentry.Config.effective_org_id() do
+        nil -> :not_found
+        org_id -> "sentry-org_id=" <> org_id
+      end
+    end
+
+    # Extract sentry-org_id from a baggage header string
+    defp extract_baggage_org_id(baggage) when is_binary(baggage) do
+      baggage
+      |> String.split(",")
+      |> Enum.find_value(fn entry ->
+        case String.split(String.trim(entry), "=", parts: 2) do
+          ["sentry-org_id", value] ->
+            trimmed = String.trim(value)
+            if trimmed == "", do: nil, else: trimmed
+
+          _ ->
+            nil
+        end
+      end)
+    end
+
+    defp extract_baggage_org_id(_), do: nil
+
+    # Determine whether to continue an incoming trace based on org_id validation
+    @doc false
+    def should_continue_trace?(raw_baggage) do
+      sdk_org_id = Sentry.Config.effective_org_id()
+      baggage_org_id = extract_baggage_org_id(raw_baggage)
+      strict = Sentry.Config.strict_trace_continuation?()
+
+      cond do
+        # Mismatched org IDs always reject
+        sdk_org_id != nil and baggage_org_id != nil and sdk_org_id != baggage_org_id ->
+          false
+
+        # In strict mode, both must be present and match (unless both are missing)
+        strict and sdk_org_id == nil and baggage_org_id == nil ->
+          true
+
+        strict ->
+          sdk_org_id != nil and sdk_org_id == baggage_org_id
+
+        true ->
+          true
+      end
+    end
   end
 end

test/sentry/config_test.exs

@@ -1,6 +1,8 @@
 defmodule Sentry.ConfigTest do
   use Sentry.Case, async: false
 
+  import Sentry.TestHelpers
+
   alias Sentry.Config
 
   describe "validate!/0" do
@@ -429,4 +431,67 @@ defmodule Sentry.ConfigTest do
       assert config[:before_send_metric] == nil
     end
   end
+
+  describe ":org_id" do
+    test "defaults to nil" do
+      assert Config.validate!([])[:org_id] == nil
+    end
+
+    test "accepts a non-empty string" do
+      assert Config.validate!(org_id: "1234567")[:org_id] == "1234567"
+    end
+
+    test "accepts nil explicitly" do
+      assert Config.validate!(org_id: nil)[:org_id] == nil
+    end
+
+    test "rejects an empty string" do
+      assert_raise ArgumentError, ~r/expected :org_id to be a non-empty string or nil/, fn ->
+        Config.validate!(org_id: "")
+      end
+    end
+
+    test "rejects a non-string value" do
+      assert_raise ArgumentError, ~r/invalid value for :org_id option/, fn ->
+        Config.validate!(org_id: 1234)
+      end
+    end
+  end
+
+  describe "effective_org_id/0" do
+    test "returns nil when no org_id is configured and DSN has no org ID" do
+      put_test_config(dsn: "https://public:secret@app.getsentry.com/1", org_id: nil)
+      assert Config.effective_org_id() == nil
+    end
+
+    test "returns explicit org_id when configured" do
+      put_test_config(org_id: "9876543")
+      assert Config.effective_org_id() == "9876543"
+    end
+
+    test "falls back to org ID extracted from DSN host" do
+      put_test_config(dsn: "https://public@o1234567.ingest.sentry.io/123", org_id: nil)
+      assert Config.effective_org_id() == "1234567"
+    end
+
+    test "explicit org_id takes precedence over DSN-derived org ID" do
+      put_test_config(dsn: "https://public@o1234567.ingest.sentry.io/123", org_id: "9999999")
+      assert Config.effective_org_id() == "9999999"
+    end
+  end
+
+  describe ":strict_trace_continuation" do
+    test "defaults to false" do
+      assert Config.validate!([])[:strict_trace_continuation] == false
+    end
+
+    test "accepts true" do
+      assert Config.validate!(strict_trace_continuation: true)[:strict_trace_continuation] == true
+    end
+
+    test "accepts false" do
+      assert Config.validate!(strict_trace_continuation: false)[:strict_trace_continuation] ==
+               false
+    end
+  end
 end