> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrating AppSignal into Phoenix

The AppSignal for Elixir package integrates with Phoenix. To set up the
integration, please follow our [installation guide](/elixir/installation).

This page will describe further ways of configuring AppSignal for the [Phoenix
framework][phoenix]. To add more custom instrumentation to your Phoenix
application, read the [Elixir
instrumentation](/elixir/instrumentation) documentation.

More information can be found in the [AppSignal Hex package
documentation][hex-appsignal].

## Installation

1. The AppSignal instrumentation for Phoenix is part of a
   separate package, which depends on the primary `appsignal` package. Add the `appsignal_phoenix` package to your `mix.exs` file.

<CodeGroup>
  ```elixir Elixir theme={null}
  # mix.exs
  defmodule AppsignalPhoenixExample.MixProject do
    # ...

    defp deps do
      [
        {:phoenix, "~> 1.5.3"},
        {:appsignal_phoenix, "~> 2.0"}
        # ...
      ]
    end
  end
  ```
</CodeGroup>

2. Then run `mix deps.get`.
3. Then run `mix appsignal.install YOUR_PUSH_API_KEY`.

After installing and configuring, the AppSignal for Phoenix package automatically starts instrumenting HTTP requests, meaning no further setup is necessary.

To gain deeper insights, AppSignal can be set up to instrument channels and live views.

## Channels

### Channel instrumentation with a channel's handle

Incoming channel requests can be instrumented by wrapping the code in your
`handle_in/3` functions with `Appsignal.Phoenix.Channel.instrument/5`:

<CodeGroup>
  ```elixir Elixir theme={null}
  defmodule AppsignalPhoenixExampleWeb.RoomChannel do
    use Phoenix.Channel

    # ...

    def handle_in("new_msg", %{"body" => body} = params, socket) do
      Appsignal.Phoenix.Channel.instrument(__MODULE__, "new_msg", params, socket, fn ->
        broadcast!(socket, "new_msg", %{body: body})
        {:noreply, socket}
      end)
    end
  end
  ```
</CodeGroup>

Alternatively, you can use function decorators to instrument channels. While
less flexible than the instrumentation function, decorators minimize the amount
of code you have to add to your application's channels.

<CodeGroup>
  ```elixir Elixir theme={null}
  defmodule SomeApp.MyChannel do
    use Appsignal.Instrumentation.Decorators

    @decorate channel_action()
    def handle_in("ping", _payload, socket) do
      # your code here..
    end
  end
  ```
</CodeGroup>

Channel events will be displayed under the "Background jobs" tab, showing the
channel module and the action argument that you entered.

## LiveView

There are two different ways to instrument live views. You can either use our
automatic telemetry handlers, or you can manually instrument your
live view handlers with our helper functions.

### Automatic telemetry handlers

<Tip>
  **Note**: The LiveView Telemetry integration is available from AppSignal for
  Phoenix version `2.1.0` onward.
</Tip>

AppSignal's LiveView Telemetry integration automatically instruments live view events.

To set it up, call `Appsignal.Phoenix.LiveView.attach/0` to attach the LiveView Telemetry handlers.
We recommend calling this function from your app's `application.ex`:

<CodeGroup>
  ```elixir Elixir theme={null}
  defmodule AppsignalPhoenixExample.Application do
    # ...
    def start(_type, _args) do
      Appsignal.Phoenix.LiveView.attach() # <--- attach the LiveView Telemetry handlers
      children = [
        # Start the Ecto repository
        AppsignalPhoenixExample.Repo,
        # Start the Telemetry supervisor
        AppsignalPhoenixExampleWeb.Telemetry,
        # Start the PubSub system
        {Phoenix.PubSub, name: AppsignalPhoenixExample.PubSub},
        # Start the Endpoint (http/https)
        AppsignalPhoenixExampleWeb.Endpoint
        # Start a worker by calling: AppsignalPhoenixExample.Worker.start_link(arg)
        # {AppsignalPhoenixExample.Worker, arg}
      ]
      # See https://hexdocs.pm/elixir/Supervisor.html
      # for other strategies and supported options
      opts = [strategy: :one_for_one, name: AppsignalPhoenixExample.Supervisor]
      Supervisor.start_link(children, opts)
    end
  end
  ```
</CodeGroup>

AppSignal will now automatically instrument all `mount`, `handle_event` and `handle_param` events under the `live_view` namespace, meaning you'll receive both performance and error insights into your live views.

### Manual helper functions

<Tip>
  If you've already configured the automatic telemetry instrumentation above,
  you do not need to manually instrument your live view handlers.
</Tip>

<Tip>
  **Note**: The LiveView helper functions are available from AppSignal for
  Elixir version `1.13.0` onward.
</Tip>

A LiveView action can also be manually instrumented by wrapping its contents in a
`Appsignal.Phoenix.LiveView.instrument/4` block.

Given a live view that updates its own state every second, we can add
AppSignal instrumentation by wrapping both the mount/2 and handle\_info/2
functions with a `Appsignal.Phoenix.LiveView.instrument`/4 call:

<CodeGroup>
  ```elixir Elixir theme={null}
  defmodule AppsignalPhoenixExampleWeb.ClockLive do
    use Phoenix.LiveView
    import Appsignal.Phoenix.LiveView, only: [instrument: 4]

    def render(assigns) do
      AppsignalPhoenixExampleWeb.ClockView.render("index.html", assigns)
    end

    def mount(_session, socket) do
      # Wrap the contents of the mount/2 function with a call to
      # Appsignal.Phoenix.LiveView.instrument/4

      instrument(__MODULE__, "mount", socket, fn ->
        :timer.send_interval(1000, self(), :tick)
        {:ok, assign(socket, state: Time.utc_now())}
      end)
    end

    def handle_info(:tick, socket) do
      # Wrap the contents of the handle_info/2 function with a call to
      # Appsignal.Phoenix.LiveView.instrument/4:

      instrument(__MODULE__, "tick", socket, fn ->
        {:ok, assign(socket, state: Time.utc_now())}
      end)
    end
  end
  ```
</CodeGroup>

Calling one of these functions in your app will now automatically create a
sample that's sent to AppSignal. These are displayed under the `:live_view`
namespace.

## Instrumentation for included Plugs

Exceptions in included Plugs are automatically caught by AppSignal, but
performance samples need to be set up manually using the custom instrumentation
helpers or decorators. See the
[Plug](/elixir/integrations/plug#instrumentation-for-included-plugs)
documentation for more information.

## Custom instrumentation

[Add custom instrumentation](/elixir/instrumentation/instrumentation) to
keep track of more complex code and get more complete breakdowns of slow
requests.

[phoenix]: http://www.phoenixframework.org/

[hex-appsignal]: https://hexdocs.pm/appsignal/