Instrumenting Ecto queries

AppSignal uses Ecto’s Telemetry instrumentation to gain information about queries ran in your app by attaching a handler that gets called whenever a query is executed.

Automatic instrumentation

The Ecto instrumentation automatically hooks into your Ecto repos if the :otp_app configuration is configured to your app's OTP app name. The installer automatically configures this for you.

config :appsignal, :config,
  otp_app: :my_app, # Set this to the name of your OTP app
  name: "My app",
  push_api_key: "your-api-key",
  env: Mix.env

The integration then uses your app's configuration to find out which repos are configured, as your app will have a configuration line like this in config/config.exs:

config :my_app,
  ecto_repos: [AppsignalPhoenixExample.Repo]

Disable automatic instrumentation

To disable automatic Ecto instrumentation, set the instrument_ecto config option to false.

Instrumenting Ecto preloads

Since Ecto preload queries internally use several Elixir processes to carry out the different database queries involved, some manual changes to your codebase are necessary for AppSignal to properly instrument them.

At the top of your Ecto repo module, replace use Ecto.Repo with use Appsignal.Ecto.Repo, as in the following example:

defmodule MyApp.Repo do
  # replace `use Ecto.Repo` with `use Appsignal.Ecto.Repo`
  use Appsignal.Ecto.Repo,
    otp_app: :my_app,
    adapter: Ecto.Adapters.Postgres
end

If your Ecto repo module has its own implementation of the default_options/1 function, make sure to call super within it to merge its default options with those of AppSignal's Ecto repo instrumentation:

defmodule MyApp.Repo do
  use Appsignal.Ecto.Repo, ...
 
  def default_options(operation) do
    super(operation) ++ [
      # ... your default options here ...
    ]
  end
end

Manual handler attachment

For repos that aren't listed in the :ecto_repos configuration, you can attach a handler manually when starting your app’s supervisor. In most applications, this is done in your application’s start/2 function.

def start(_type, _args) do
  children = [
    AppsignalPhoenixExample.Repo,
    AppsignalPhoenixExampleWeb.Endpoint
  ]
 
  Appsignal.Ecto.attach(:my_otp_app, MyApp.Repo)
 
  opts = [strategy: :one_for_one, name: AppsignalPhoenixExample.Supervisor]
  Supervisor.start_link(children, opts)
end

In this example, we’ve attached the Telemetry handler to our Phoenix application by calling Appsignal.Ecto.attach/2. The first argument is the name of the OTP app that the repo belongs to, and the second argument is the repo's module.

Metrics

In addition to instrumenting your Ecto queries, AppSignal for Elixir collects metrics about your Ecto repos' performance:

• ecto_query_time: The time the database spends executing each query, tagged by repo and hostname, and for each table by repo and source.

• ecto_queue_time: The time spent waiting for a database connection from the pool, tagged by repo and hostname.

• ecto_decode_time: The time spent decoding query results into Elixir terms, tagged by repo and hostname, and for each table by repo and source.

• ecto_idle_time: The time the connection sat idle in the pool before being checked out, tagged by repo and hostname.

• ecto_total_time: The sum of queue, query, and decode time, tagged by repo and hostname, and for each table by repo and source.

AppSignal uses these metrics to create the Ecto automated dashboard, which shows key insights into your Ecto repos' performance: