feat(tracing): nest LV spans under root traces

Author: solnic

lib/sentry/opentelemetry/live_view_propagator.ex

@@ -0,0 +1,194 @@
+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
+      # During static render (HTTP request phase), the HTTP span already covers
+      # this phase, so we skip context propagation to avoid redundant work.
+      #
+      # For WebSocket connections, we need to propagate the trace context from
+      # the session so spans are correctly parented to the original HTTP request.
+      unless static_render?(socket) do
+        propagate_context_if_needed(socket)
+      end
+
+      :ok
+    end
+
+    # Check if this is a static render (not connected via WebSocket)
+    defp static_render?(socket) do
+      # During static render, transport_pid is nil
+      socket.transport_pid == nil
+    end
+
+    defp propagate_context_if_needed(socket) do
+      # Try to get trace context from socket's private assigns
+      case get_context_carrier(socket) do
+        nil ->
+          :ok
+
+        carrier when is_map(carrier) and map_size(carrier) > 0 ->
+          # Only propagate context if we don't already have a valid span attached.
+          # This prevents overwriting existing trace context during nested operations.
+          current_span_ctx = :otel_tracer.current_span_ctx()
+
+          _ =
+            unless has_valid_span?(current_span_ctx) do
+              # Extract and attach the trace context from the session
+              ctx = :otel_ctx.get_current()
+
+              new_ctx =
+                Sentry.OpenTelemetry.Propagator.extract(
+                  ctx,
+                  carrier,
+                  &map_keys/1,
+                  &map_getter/2,
+                  []
+                )
+
+              :otel_ctx.attach(new_ctx)
+            end
+
+          :ok
+
+        _ ->
+          :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()
+
+      # The session can be in different places depending on the connection type:
+      # 1. WebSocket: socket.private.connect_info.session (map)
+      # 2. Static render (test): socket.private.connect_info is a %Plug.Conn{}
+      case socket do
+        # WebSocket connection has session as a map
+        %{private: %{connect_info: %{session: session}}} when is_map(session) ->
+          Map.get(session, session_key)
+
+        # Static render (Phoenix.LiveViewTest) has connect_info as Plug.Conn
+        %{private: %{connect_info: %Plug.Conn{private: %{plug_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?(:undefined), do: false
+    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,23 +28,92 @@ 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
+      # Filter redundant LiveView spans from static renders.
+      # During static render, the HTTP server span already covers the request,
+      # so LiveView lifecycle spans (mount, handle_params, etc.) are duplicates.
+      if skip_static_render_liveview_span?(span_record) do
+        true
+      else
+        process_span(span_record)
+      end
+    end
+
+    # Skip LiveView spans that occur during static render (HTTP request phase).
+    # These are redundant because the HTTP server span already covers this phase.
+    # We detect this by checking if:
+    # 1. The span is a LiveView lifecycle span (mount, handle_params, handle_event)
+    # 2. It has a local parent span that is an HTTP server span
+    defp skip_static_render_liveview_span?(span_record) do
+      is_liveview_span?(span_record) and has_local_http_parent?(span_record)
+    end
+
+    # Check if span name matches LiveView lifecycle patterns from opentelemetry_phoenix
+    # Span names are like "MyAppWeb.SomeLive.mount", "MyAppWeb.SomeLive.handle_params", etc.
+    # Note: handle_event spans have the event name appended like "Module.handle_event#event_name"
+    defp is_liveview_span?(%{name: name}) when is_binary(name) do
+      is_liveview_lifecycle_span?(name)
+    end
+
+    defp is_liveview_span?(_), do: false
+
+    # Check if the span has a local parent that is an HTTP server span
+    defp has_local_http_parent?(%{parent_span_id: nil}), do: false
+
+    defp has_local_http_parent?(%{parent_span_id: parent_span_id}) do
+      case SpanStorage.get_span(parent_span_id) do
+        nil -> false
+        parent_span -> is_http_server_span?(parent_span)
+      end
+    end
+
+    defp is_http_server_span?(%{kind: :server, attributes: attributes}) do
+      Map.has_key?(attributes, to_string(HTTPAttributes.http_request_method()))
+    end
+
+    defp is_http_server_span?(_), do: false
+
+    defp process_span(span_record) do
+      SpanStorage.store_span(span_record)
+
+      # 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
 
     defp build_and_send_transaction(span_record) do
@@ -82,6 +147,31 @@ if Sentry.OpenTelemetry.VersionChecker.tracing_compatible?() do
       :ok
     end
 
+    # Helper function to detect if a span is a server span that should be
+    # treated as a transaction root for distributed tracing.
+    # This includes HTTP server request spans (have http.request.method attribute)
+    # and LiveView lifecycle spans (mount, handle_params, handle_event)
+    defp is_server_span?(%{kind: :server, attributes: attributes, name: name}) do
+      # Check if it's an HTTP server request span (has http.request.method)
+      # LiveView lifecycle spans (opentelemetry_phoenix uses kind: :server)
+      Map.has_key?(attributes, to_string(HTTPAttributes.http_request_method())) or
+        is_liveview_lifecycle_span?(name)
+    end
+
+    defp is_server_span?(_), do: false
+
+    # Check if span name matches LiveView lifecycle patterns
+    # Note: handle_event spans have the event name appended like "Module.handle_event#event_name"
+    # So we check if the name contains these patterns, not just ends with them
+    defp is_liveview_lifecycle_span?(name) when is_binary(name) do
+      String.ends_with?(name, ".mount") or
+        String.ends_with?(name, ".handle_params") or
+        String.contains?(name, ".handle_event#") or
+        String.ends_with?(name, ".handle_event")
+    end
+
+    defp is_liveview_lifecycle_span?(_), do: false
+
     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))
@@ -134,7 +224,13 @@ if Sentry.OpenTelemetry.VersionChecker.tracing_compatible?() do
       client_address =
         Map.get(span_record.attributes, to_string(ClientAttributes.client_address()))
 
-      url_path = Map.get(span_record.attributes, to_string(URLAttributes.url_path()))
+      # Try multiple attributes for the URL path
+      url_path =
+        Map.get(span_record.attributes, to_string(URLAttributes.url_path())) ||
+          Map.get(span_record.attributes, "url.full") ||
+          Map.get(span_record.attributes, "http.target") ||
+          Map.get(span_record.attributes, "http.route") ||
+          span_record.name
 
       # Build description with method and path
       description =