opentelemetry-erlang-contrib/instrumentation/opentelemetry_phoenix/lib/opentelemetry_phoenix.ex

defmodule OpentelemetryPhoenix do
  @options_schema NimbleOptions.new!(
                    endpoint_prefix: [
                      type: {:list, :atom},
                      default: [:phoenix, :endpoint],
                      doc: "The endpoint prefix in your endpoint."
                    ],
                    adapter: [
                      type: {:in, [:cowboy2, nil]},
                      default: nil,
                      doc: "The phoenix server adapter being used.",
                      type_doc: ":atom"
                    ],
                    liveview: [
                      type: :boolean,
                      default: true,
                      doc: "Whether LiveView traces will be instrumented."
                    ]
                  )

  @moduledoc """
  OpentelemetryPhoenix uses [telemetry](https://hexdocs.pm/telemetry/) handlers to create `OpenTelemetry` spans.

  Current events which are supported include endpoint start/stop, router start/stop,
  and router exceptions.

  ### Supported options
  #{NimbleOptions.docs(@options_schema)}

  If you are using PlugCowboy as your adapter you can add `:opentelemetry_cowboy` to your project
  and pass the `:adapter` option when calling setup. Setting this option will prevent a new
  span from being started and the existing cowboy span to be continued. This is the recommended
  setup for measuring accurate latencies.

  `Bandit.PhoenixAdapter` is not currently supported.

  ## Usage

  In your application start:

      def start(_type, _args) do
        :opentelemetry_cowboy.setup()
        OpentelemetryPhoenix.setup(adapter: :cowboy2)

        children = [
          {Phoenix.PubSub, name: MyApp.PubSub},
          MyAppWeb.Endpoint
        ]

        opts = [strategy: :one_for_one, name: MyStore.Supervisor]
        Supervisor.start_link(children, opts)
      end

  """
  require OpenTelemetry.Tracer
  alias OpenTelemetry.SemanticConventions
  alias OpenTelemetry.Tracer
  alias OpentelemetryPhoenix.Reason

  require SemanticConventions.Trace
  require OpenTelemetry.Tracer

  @tracer_id __MODULE__

  @typedoc "Setup options"
  @type opts :: [endpoint_prefix() | adapter()]

  @typedoc "The endpoint prefix in your endpoint. Defaults to `[:phoenix, :endpoint]`"
  @type endpoint_prefix :: {:endpoint_prefix, [atom()]}

  @typedoc "The phoenix server adapter being used. Optional"
  @type adapter :: {:adapter, :cowboy2 | term()}

  @doc """
  Initializes and configures the telemetry handlers.
  """
  @spec setup(opts()) :: :ok
  def setup(opts \\ []) do
    opts = NimbleOptions.validate!(opts, @options_schema)

    attach_endpoint_start_handler(opts)
    attach_endpoint_stop_handler(opts)
    attach_router_start_handler()
    attach_router_dispatch_exception_handler()

    if opts[:liveview] do
      attach_liveview_handlers()
    end

    :ok
  end

  @doc false
  def attach_endpoint_start_handler(opts) do
    :telemetry.attach(
      {__MODULE__, :endpoint_start},
      opts[:endpoint_prefix] ++ [:start],
      &__MODULE__.handle_endpoint_start/4,
      %{adapter: opts[:adapter]}
    )
  end

  @doc false
  def attach_endpoint_stop_handler(opts) do
    :telemetry.attach(
      {__MODULE__, :endpoint_stop},
      opts[:endpoint_prefix] ++ [:stop],
      &__MODULE__.handle_endpoint_stop/4,
      %{adapter: opts[:adapter]}
    )
  end

  @doc false
  def attach_router_start_handler do
    :telemetry.attach(
      {__MODULE__, :router_dispatch_start},
      [:phoenix, :router_dispatch, :start],
      &__MODULE__.handle_router_dispatch_start/4,
      %{}
    )
  end

  @doc false
  def attach_router_dispatch_exception_handler do
    :telemetry.attach(
      {__MODULE__, :router_dispatch_exception},
      [:phoenix, :router_dispatch, :exception],
      &__MODULE__.handle_router_dispatch_exception/4,
      %{}
    )
  end

  def attach_liveview_handlers do
    :telemetry.attach_many(
      {__MODULE__, :live_view},
      [
        [:phoenix, :live_view, :mount, :start],
        [:phoenix, :live_view, :mount, :stop],
        [:phoenix, :live_view, :mount, :exception],
        [:phoenix, :live_view, :handle_params, :start],
        [:phoenix, :live_view, :handle_params, :stop],
        [:phoenix, :live_view, :handle_params, :exception],
        [:phoenix, :live_view, :handle_event, :start],
        [:phoenix, :live_view, :handle_event, :stop],
        [:phoenix, :live_view, :handle_event, :exception],
        [:phoenix, :live_component, :handle_event, :start],
        [:phoenix, :live_component, :handle_event, :stop],
        [:phoenix, :live_component, :handle_event, :exception]
      ],
      &__MODULE__.handle_liveview_event/4,
      %{}
    )

    :ok
  end

  @doc false
  def handle_endpoint_start(_event, _measurements, meta, config) do
    Process.put({:otel_phoenix, :adapter}, config.adapter)

    case adapter() do
      :cowboy2 ->
        cowboy2_start()

      _ ->
        default_start(meta)
    end
  end

  defp cowboy2_start do
    OpentelemetryProcessPropagator.fetch_parent_ctx()
    |> OpenTelemetry.Ctx.attach()
  end

  defp default_start(meta) do
    %{conn: conn} = meta
    :otel_propagator_text_map.extract(conn.req_headers)

    peer_data = Plug.Conn.get_peer_data(conn)

    user_agent = header_value(conn, "user-agent")
    peer_ip = Map.get(peer_data, :address)

    attributes = %{
      SemanticConventions.Trace.http_client_ip() => client_ip(conn),
      SemanticConventions.Trace.http_flavor() => http_flavor(conn.adapter),
      SemanticConventions.Trace.http_method() => conn.method,
      SemanticConventions.Trace.http_scheme() => "#{conn.scheme}",
      SemanticConventions.Trace.http_target() => conn.request_path,
      SemanticConventions.Trace.http_user_agent() => user_agent,
      SemanticConventions.Trace.net_host_name() => conn.host,
      SemanticConventions.Trace.net_sock_host_addr() => to_string(:inet_parse.ntoa(conn.remote_ip)),
      SemanticConventions.Trace.net_host_port() => conn.port,
      SemanticConventions.Trace.net_sock_peer_addr() => to_string(:inet_parse.ntoa(peer_ip)),
      SemanticConventions.Trace.net_peer_port() => peer_data.port,
      SemanticConventions.Trace.net_transport() => :"IP.TCP"
    }

    # start the span with a default name. Route name isn't known until router dispatch
    OpentelemetryTelemetry.start_telemetry_span(@tracer_id, "HTTP #{conn.method}", meta, %{
      kind: :server,
      attributes: attributes
    })
  end

  @doc false
  def handle_endpoint_stop(_event, _measurements, meta, _config) do
    case adapter() do
      :cowboy2 ->
        :ok

      _ ->
        default_stop(meta)
    end
  end

  defp default_stop(meta) do
    %{conn: conn} = meta

    # ensure the correct span is current and update the status
    OpentelemetryTelemetry.set_current_telemetry_span(@tracer_id, meta)

    Tracer.set_attribute(SemanticConventions.Trace.http_status_code(), conn.status)

    if conn.status >= 500 do
      Tracer.set_status(OpenTelemetry.status(:error, ""))
    end

    # end the Phoenix span
    OpentelemetryTelemetry.end_telemetry_span(@tracer_id, meta)
  end

  @doc false
  def handle_router_dispatch_start(_event, _measurements, meta, _config) do
    attributes = %{
      :"phoenix.plug" => meta.plug,
      :"phoenix.action" => meta.plug_opts,
      SemanticConventions.Trace.http_route() => meta.route
    }

    Tracer.update_name("#{meta.route}")
    Tracer.set_attributes(attributes)
  end

  @doc false
  def handle_router_dispatch_exception(
        _event,
        _measurements,
        %{kind: kind, reason: reason, stacktrace: stacktrace},
        _config
      ) do
    if OpenTelemetry.Span.is_recording(OpenTelemetry.Tracer.current_span_ctx()) do
      {[reason: reason], attrs} =
        Reason.normalize(reason)
        |> Keyword.split([:reason])

      # try to normalize all errors to Elixir exceptions
      exception = Exception.normalize(kind, reason, stacktrace)

      # record exception and mark the span as errored
      Tracer.record_exception(exception, stacktrace, attrs)

      # do not close the span as endpoint stop will still be called with
      # more info, including the status code, which is nil at this stage
    end
  end

  def handle_liveview_event(
        [:phoenix, _live, :mount, :start],
        _measurements,
        meta,
        _handler_configuration
      ) do
    %{socket: socket} = meta
    %{view: live_view} = socket

    attributes = %{}

    OpentelemetryTelemetry.start_telemetry_span(
      @tracer_id,
      "#{inspect(live_view)}.mount",
      meta,
      %{kind: :server}
    )
    |> OpenTelemetry.Span.set_attributes(attributes)
  end

  def handle_liveview_event(
        [:phoenix, _live, :handle_params, :start],
        _measurements,
        meta,
        _handler_configuration
      ) do
    %{socket: socket} = meta
    %{view: live_view} = socket

    attributes = %{}

    OpentelemetryTelemetry.start_telemetry_span(
      @tracer_id,
      "#{inspect(live_view)}.handle_params",
      meta,
      %{kind: :server}
    )
    |> OpenTelemetry.Span.set_attributes(attributes)
  end

  def handle_liveview_event(
        [:phoenix, _live, :handle_event, :start],
        _measurements,
        meta,
        _handler_configuration
      ) do
    %{socket: socket, event: event, params: _params} = meta
    %{view: live_view} = socket

    attributes = %{}

    OpentelemetryTelemetry.start_telemetry_span(
      @tracer_id,
      "#{inspect(live_view)}.handle_event##{event}",
      meta,
      %{kind: :server}
    )
    |> OpenTelemetry.Span.set_attributes(attributes)
  end

  def handle_liveview_event(
        [:phoenix, _live, _event, :stop],
        _measurements,
        meta,
        _handler_configuration
      ) do
    OpentelemetryTelemetry.end_telemetry_span(@tracer_id, meta)
  end

  def handle_liveview_event(
        [:phoenix, _live, _action, :exception],
        _,
        %{kind: kind, reason: reason, stacktrace: stacktrace} = meta,
        _
      ) do
    ctx = OpentelemetryTelemetry.set_current_telemetry_span(@tracer_id, meta)

    exception = Exception.normalize(kind, reason, stacktrace)

    OpenTelemetry.Span.record_exception(ctx, exception, stacktrace, [])
    OpenTelemetry.Span.set_status(ctx, OpenTelemetry.status(:error, ""))
    OpentelemetryTelemetry.end_telemetry_span(@tracer_id, meta)
  end

  defp http_flavor({_adapter_name, meta}) do
    case Map.get(meta, :version) do
      :"HTTP/1.0" -> :"1.0"
      :"HTTP/1.1" -> :"1.1"
      :"HTTP/2.0" -> :"2.0"
      :"HTTP/2" -> :"2.0"
      :SPDY -> :SPDY
      :QUIC -> :QUIC
      nil -> ""
    end
  end

  defp client_ip(%{remote_ip: remote_ip} = conn) do
    case header_value(conn, "x-forwarded-for") do
      "" ->
        remote_ip
        |> :inet_parse.ntoa()
        |> to_string()

      ip_address ->
        ip_address
        |> String.split(",", parts: 2)
        |> List.first()
    end
  end

  defp header_value(conn, header) do
    case Plug.Conn.get_req_header(conn, header) do
      [] ->
        ""

      [value | _] ->
        value
    end
  end

  defp adapter do
    Process.get({:otel_phoenix, :adapter})
  end
end