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.

Ecto query events are attached to the current AppSignal transaction. Phoenix and Plug applications start this transaction automatically for each request. In pure Elixir projects, no transaction is started for you, so query events are only reported once you start one yourself. See Starting new transactions.

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 Intelligence dashboard with the following graphs:

Query time: 95th percentile of time the database spent executing each query, per table.
Throughput: number of queries per table.
Total time: 95th percentile of total Ecto time (queue, query, and decode), per table.
Decode time: mean time spent decoding query results into Elixir terms, per table.
Queue time: 95th percentile of time spent waiting for a database connection from the pool, per host.
Idle time: mean time connections sat idle in the pool before being checked out, per host.
Total time per host: mean total Ecto time (queue, query, and decode), per host.

Intelligence dashboard showing key Ecto metrics — The Ecto Intelligence dashboard in AppSignal

SDKs & telemetry

Language SDKs

Telemetry tools

Automatic instrumentation

Disable automatic instrumentation

Instrumenting Ecto preloads

Manual handler attachment

Metrics

​Automatic instrumentation

​Disable automatic instrumentation

​Instrumenting Ecto preloads

​Manual handler attachment

​Metrics

Automatic instrumentation

Disable automatic instrumentation

Instrumenting Ecto preloads

Manual handler attachment

Metrics