feat(tracing): support for nested LiveView spans

Author: solnic

lib/sentry/opentelemetry/live_view_propagator.ex

@@ -0,0 +1,156 @@
+if Sentry.OpenTelemetry.VersionChecker.tracing_compatible?() and
+     Code.ensure_loaded?(Phoenix.LiveView) do
+  defmodule Sentry.OpenTelemetry.LiveViewPropagator do
+    @moduledoc """
+    Telemetry handler that propagates OpenTelemetry context to LiveView processes.
+
+    This module attaches telemetry handlers for LiveView lifecycle events
+    (mount, handle_params, handle_event) that run BEFORE `opentelemetry_phoenix`
+    creates spans, ensuring the correct parent trace context is attached.
+
+    ## Why This Is Needed
+
+    When a browser makes an HTTP request with distributed tracing headers, the trace
+    context is correctly extracted for the initial request. However, Phoenix LiveView
+    spawns new BEAM processes for WebSocket connections that handle lifecycle callbacks.
+
+    `opentelemetry_phoenix` uses telemetry handlers to create spans for these events.
+    If we don't inject the parent context BEFORE those handlers run, each LiveView
+    span becomes a new root trace instead of being nested under the original HTTP request.
+
+    This module solves this by:
+    1. Using `Sentry.Plug.LiveViewContext` to store trace context in the session during the initial HTTP request
+    2. Attaching telemetry handlers with higher priority (registered first) than `opentelemetry_phoenix`
+    3. Extracting the context from the session and attaching it before `opentelemetry_phoenix` creates spans
+
+    ## Usage
+
+    Call `setup/0` in your application's start function, **BEFORE** calling
+    `OpentelemetryPhoenix.setup/1`:
+
+        def start(_type, _args) do
+          # Set up Sentry's LiveView context propagation FIRST
+          Sentry.OpenTelemetry.LiveViewPropagator.setup()
+
+          # Then set up OpentelemetryPhoenix
+          OpentelemetryPhoenix.setup(adapter: :bandit)
+
+          children = [
+            # ...
+          ]
+
+          Supervisor.start_link(children, strategy: :one_for_one)
+        end
+
+    Also add `Sentry.Plug.LiveViewContext` to your router pipeline:
+
+        pipeline :browser do
+          plug :accepts, ["html"]
+          plug :fetch_session
+          # ... other plugs
+          plug Sentry.Plug.LiveViewContext
+        end
+
+    *Available since v12.0.0.*
+    """
+
+    @moduledoc since: "12.0.0"
+
+    require Logger
+    require Record
+
+    @span_ctx_fields Record.extract(:span_ctx,
+                       from_lib: "opentelemetry_api/include/opentelemetry.hrl"
+                     )
+    Record.defrecordp(:span_ctx, @span_ctx_fields)
+
+    @handler_id {__MODULE__, :live_view_context}
+
+    @doc """
+    Attaches telemetry handlers for LiveView context propagation.
+
+    Must be called BEFORE `OpentelemetryPhoenix.setup/1` to ensure handlers
+    run in the correct order.
+    """
+    @spec setup() :: :ok
+    def setup do
+      events = [
+        [:phoenix, :live_view, :mount, :start],
+        [:phoenix, :live_view, :handle_params, :start],
+        [:phoenix, :live_view, :handle_event, :start],
+        [:phoenix, :live_component, :handle_event, :start]
+      ]
+
+      _ =
+        :telemetry.attach_many(
+          @handler_id,
+          events,
+          &__MODULE__.handle_event/4,
+          %{}
+        )
+
+      :ok
+    end
+
+    @doc """
+    Detaches the telemetry handlers. Mainly useful for testing.
+    """
+    @spec teardown() :: :ok | {:error, :not_found}
+    def teardown do
+      :telemetry.detach(@handler_id)
+    end
+
+    @doc false
+    def handle_event(_event, _measurements, %{socket: socket} = _meta, _config) do
+      case get_context_carrier(socket) do
+        carrier when is_map(carrier) and map_size(carrier) > 0 ->
+          current_span_ctx = :otel_tracer.current_span_ctx()
+
+          # Extract and attach the trace context from the session if needed
+          if has_valid_span?(current_span_ctx) do
+            :ok
+          else
+            new_ctx =
+              Sentry.OpenTelemetry.Propagator.extract(
+                :otel_ctx.get_current(),
+                carrier,
+                &map_keys/1,
+                &map_getter/2,
+                []
+              )
+
+            :otel_ctx.attach(new_ctx)
+          end
+
+        nil ->
+          :ok
+      end
+    end
+
+    # Try to get the carrier from socket private assigns
+    defp get_context_carrier(socket) do
+      session_key = Sentry.Plug.LiveViewContext.session_key()
+
+      case socket do
+        %{private: %{connect_info: %{session: session}}} when is_map(session) ->
+          Map.get(session, session_key)
+
+        _ ->
+          nil
+      end
+    end
+
+    # Check if span context has a valid (non-zero) trace ID
+    defp has_valid_span?(span_ctx(trace_id: trace_id)) when trace_id != 0, do: true
+    defp has_valid_span?(_), do: false
+
+    defp map_keys(carrier), do: Map.keys(carrier)
+
+    defp map_getter(key, carrier) do
+      case Map.fetch(carrier, key) do
+        {:ok, value} -> value
+        :error -> :undefined
+      end
+    end
+  end
+end

lib/sentry/opentelemetry/span_processor.ex

@@ -16,10 +16,6 @@ if Sentry.OpenTelemetry.VersionChecker.tracing_compatible?() do
     alias Sentry.{Transaction, OpenTelemetry.SpanStorage, OpenTelemetry.SpanRecord}
     alias Sentry.Interfaces.Span
 
-    # Extract span record fields to access parent_span_id in on_start
-    @span_fields Record.extract(:span, from_lib: "opentelemetry/include/otel_span.hrl")
-    Record.defrecordp(:span, @span_fields)
-
     @impl :otel_span_processor
     def on_start(_ctx, otel_span, _config) do
       span_record = SpanRecord.new(otel_span)
@@ -32,25 +28,71 @@ if Sentry.OpenTelemetry.VersionChecker.tracing_compatible?() do
       span_record = SpanRecord.new(otel_span)
       SpanStorage.update_span(span_record)
 
-      if is_transaction_root?(span_record) do
+      process_span(span_record)
+    end
+
+    @impl :otel_span_processor
+    def force_flush(_config) do
+      :ok
+    end
+
+    defp process_span(span_record) do
+      # Check if this is a root span (no parent) or a transaction root
+      #
+      # A span should be a transaction root if:
+      # 1. It has no parent (true root span)
+      # 2. OR it's a server span with only a REMOTE parent (distributed tracing)
+      #
+      # A span should NOT be a transaction root if:
+      # - It has a LOCAL parent (parent span exists in our SpanStorage)
+      #
+      # Note: LiveView spans during static render are filtered earlier by
+      # skip_static_render_liveview_span?/1, so we don't need to handle them here.
+      is_transaction_root =
+        cond do
+          # No parent = definitely a root
+          span_record.parent_span_id == nil ->
+            true
+
+          # Has a parent - check if it's local or remote
+          true ->
+            has_local_parent = has_local_parent_span?(span_record.parent_span_id)
+
+            if has_local_parent do
+              # Parent exists locally - this is a child span, not a transaction root
+              false
+            else
+              # Parent is remote (distributed tracing) - treat server spans as transaction roots
+              is_server_span?(span_record)
+            end
+        end
+
+      if is_transaction_root do
         build_and_send_transaction(span_record)
       else
         true
       end
     end
 
-    # Check if this is a root span (no parent) or a transaction root
-    #
-    # A span should be a transaction root if:
-    #
-    # 1. It has no parent (true root span)
-    # 2. OR it's a span with a remote parent span
-    #
-    defp is_transaction_root?(span_record) do
-      span_record.parent_span_id == nil or
-        not SpanStorage.span_exists?(span_record.parent_span_id)
+    defp has_local_parent_span?(parent_span_id) do
+      SpanStorage.span_exists?(parent_span_id)
     end
 
+    # Check if it's an HTTP server request span or a LiveView span
+    defp is_server_span?(%{kind: :server} = span_record) do
+      is_http_server_span?(span_record) or is_liveview_span?(span_record)
+    end
+
+    defp is_server_span?(_), do: false
+
+    defp is_http_server_span?(%{kind: :server, attributes: attributes}) do
+      Map.has_key?(attributes, to_string(HTTPAttributes.http_request_method()))
+    end
+
+    # Check if span name matches LiveView lifecycle patterns
+    defp is_liveview_span?(%{origin: "opentelemetry_phoenix"}), do: true
+    defp is_liveview_span?(_), do: false
+
     defp build_and_send_transaction(span_record) do
       child_span_records = SpanStorage.get_child_spans(span_record.span_id)
       transaction = build_transaction(span_record, child_span_records)
@@ -77,11 +119,6 @@ if Sentry.OpenTelemetry.VersionChecker.tracing_compatible?() do
       result
     end
 
-    @impl :otel_span_processor
-    def force_flush(_config) do
-      :ok
-    end
-
     defp build_transaction(root_span_record, child_span_records) do
       root_span = build_span(root_span_record)
       child_spans = Enum.map(child_span_records, &build_span(&1))

lib/sentry/opentelemetry/span_storage.ex

@@ -53,6 +53,26 @@ if Sentry.OpenTelemetry.VersionChecker.tracing_compatible?() do
       end
     end
 
+    @doc """
+    Retrieves a span by its ID, regardless of whether it's a root or child span.
+    Returns nil if the span is not found.
+    """
+    @spec get_span(String.t(), keyword()) :: SpanRecord.t() | nil
+    def get_span(span_id, opts \\ []) do
+      table_name = Keyword.get(opts, :table_name, default_table_name())
+
+      case :ets.lookup(table_name, {:root_span, span_id}) do
+        [{{:root_span, ^span_id}, span, _stored_at}] ->
+          span
+
+        [] ->
+          case :ets.match_object(table_name, {{:child_span, :_, span_id}, :_, :_}) do
+            [{_key, span, _stored_at} | _] -> span
+            [] -> nil
+          end
+      end
+    end
+
     @spec store_span(SpanRecord.t(), keyword()) :: true
     def store_span(span_data, opts \\ []) do
       table_name = Keyword.get(opts, :table_name, default_table_name())
@@ -137,6 +157,16 @@ if Sentry.OpenTelemetry.VersionChecker.tracing_compatible?() do
       :ok
     end
 
+    @spec remove_child_span(String.t(), String.t(), keyword()) :: :ok
+    def remove_child_span(parent_span_id, span_id, opts \\ []) do
+      table_name = Keyword.get(opts, :table_name, default_table_name())
+      key = {:child_span, parent_span_id, span_id}
+
+      :ets.delete(table_name, key)
+
+      :ok
+    end
+
     defp schedule_cleanup(interval) do
       Process.send_after(self(), :cleanup_stale_spans, interval)
     end