Elixir Agent

Requirements

Our Elixir agent supports Elixir 1.14+, Phoenix 1.6+ (optional), and Ecto 3.x. We also instrument LiveView, Oban, Finch, and Tesla packages.

Optional dependencies:

• phoenix_live_view ~> 0.18 or ~> 1.0 — Required for LiveView and HEEx instrumentation

Installation

Tailored instructions are provided within our user interface. General instructions for a Phoenix app:

1. Add the scout_apm dependency.

Your mix.exs file:

# mix.exs

 def deps do
   [{:phoenix, "~> 1.6"},
    ...
    {:scout_apm, "~> 2.0"}]
 end

Shell:

mix deps.get

2. Download your customized config file, placing it at config/scout_apm.exs.

Your customized config file is available within your Scout account. Inside the file, replace "YourApp" with the app name you’d like to appear within Scout.

3. Integrate into your Phoenix app.

Instrument Controllers. In lib/your_app_web.ex:

# lib/your_app_web.ex
defmodule YourApp.Web do
  def controller do
    quote do
      use Phoenix.Controller
      use ScoutApm.Instrumentation
      ...

Instrument Templates. In config/config.exs:

# config/config.exs
config :phoenix, :template_engines,
  eex: ScoutApm.Instruments.EExEngine,
  exs: ScoutApm.Instruments.ExsEngine,
  heex: ScoutApm.Instruments.HEExEngine

4. Integrate Ecto

In lib/my_app/application.ex:

# lib/my_app/application.ex
defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    children = [
        # ...
    ]
    :ok = ScoutApm.Instruments.EctoTelemetry.attach(MyApp.Repo)
    # ...
    Supervisor.start_link(children, opts)
  end
end

5. (Optional) Attach telemetry handlers for additional instrumentation.

In your Application.start/2 function, attach handlers for the libraries you use:

# lib/my_app/application.ex
def start(_type, _args) do
  # Attach Scout APM telemetry handlers
  ScoutApm.Instruments.LiveViewTelemetry.attach()        # Phoenix LiveView
  ScoutApm.Instruments.ObanTelemetry.attach()             # Oban background jobs
  ScoutApm.Instruments.FinchTelemetry.attach()            # Finch/Req HTTP client
  ScoutApm.Instruments.TeslaTelemetry.attach()            # Tesla HTTP client
  ScoutApm.Instruments.PhoenixErrorTelemetry.attach()     # Error monitoring

  children = [
    # ...
  ]
  Supervisor.start_link(children, opts)
end

6. Restart your app.

mix phx.server

Updating to the Newest Version

1. Ensure your mix.exs dependency entry for scout_apm is: {:scout_apm, "~> 2.0"}

2.

mix deps.get scout_apm

3. Recompile and deploy.

Auto-Instrumented Libraries

Our install instructions walk through instrumenting the following libraries:

• Phoenix
  • controllers
  • views
  • templates (EEx, Exs, and HEEx)
• Ecto 3.x (with database metrics)
• Phoenix LiveView (via telemetry)
• Oban (via telemetry)
• Finch / Req (via telemetry — External Services)
• Tesla (via telemetry — External Services)

See instrumenting common libraries for guides on instrumenting other Elixir libraries.