feat: Add strict trace continuation support

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,69 @@ 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
+        if baggage == "" do
+          "sentry-org_id=" <> org_id
+        else
+          baggage <> ",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,66 @@ 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