Configuring metrics

This guide covers how to install and configure your LiveDashboard Metrics.

Installing metrics

To enable the "Metrics" functionality in your dashboard, you will need to do the three steps below:

1. Add the telemetry dependencies
2. Define your telemetry module
3. Configure the dashboard

Add the telemetry dependencies

In your mix.exs, add the following to your deps:

  {:telemetry_poller, "~> 0.4"},
  {:telemetry_metrics, "~> 0.4"},

If you generated your Phoenix app in version v1.5+, these dependencies will already be installed. You can also skip the next section.

Define your telemetry module

In your Phoenix application, we recommend that you create a module to act as your telemetry supervision tree. Within this supervisor you can define your application's metrics and start your reporters.

The example below contains the child spec for a LiveDashboard reporter, as well as some metrics definitions for telemetry events emitted by Phoenix, Ecto, and the VM (via the :telemetry_poller package).

Create your Telemetry module in lib/my_app_web/telemetry.ex:

defmodule MyAppWeb.Telemetry do
  use Supervisor
  import Telemetry.Metrics

  def start_link(arg) do
    Supervisor.start_link(__MODULE__, arg, name: __MODULE__)
  end

  @impl true
  def init(_arg) do
    children = [
      # Telemetry poller will execute the given period measurements
      # every 10_000ms. Learn more here: https://hexdocs.pm/telemetry_metrics
      {:telemetry_poller, measurements: periodic_measurements(), period: 10_000}
      # Add reporters as children of your supervision tree.
      # {Telemetry.Metrics.ConsoleReporter, metrics: metrics()}
    ]

    Supervisor.init(children, strategy: :one_for_one)
  end

  def metrics do
    [
      # Phoenix Metrics
      summary("phoenix.endpoint.stop.duration",
        unit: {:native, :millisecond}
      ),
      summary("phoenix.router_dispatch.stop.duration",
        tags: [:route],
        unit: {:native, :millisecond}
      ),

      # Database Time Metrics
      summary("my_app.repo.query.total_time", unit: {:native, :millisecond}),
      summary("my_app.repo.query.decode_time", unit: {:native, :millisecond}),
      summary("my_app.repo.query.query_time", unit: {:native, :millisecond}),
      summary("my_app.repo.query.queue_time", unit: {:native, :millisecond}),
      summary("my_app.repo.query.idle_time", unit: {:native, :millisecond}),

      # VM Metrics
      summary("vm.memory.total", unit: {:byte, :kilobyte}),
      summary("vm.total_run_queue_lengths.total"),
      summary("vm.total_run_queue_lengths.cpu"),
      summary("vm.total_run_queue_lengths.io")
    ]
  end

  defp periodic_measurements do
    []
  end
end

Make sure to replace MyApp and my_app by your actual application name.

Then add to your main application's supervision tree (usually in lib/my_app/application.ex):

children = [
  MyApp.Repo,
  MyAppWeb.Telemetry,
  MyAppWeb.Endpoint,
  ...
]

Configure the dashboard

The last step now is to configure the dashboard. Go to the live_dashboard call in your router and add the following option:

live_dashboard "/dashboard", metrics: MyAppWeb.Telemetry

Now refresh the "/dashboard" page and the metrics functionality should be enabled. Each metric goes to a distinct group based on the metric name itself.

Providing history for metrics

If you wish to populate metrics with history saved from telemetry or another data source, modify the config above like so:

live_dashboard "/dashboard",
  metrics: MyAppWeb.Telemetry,
  metrics_history: {MyStorage, :metrics_history, []}

where MyStorage is a module and :metrics_history is a function taking a single argument in this example, which will always be a metric. The function must return a list, empty if there is no data, or a list of maps with :label, :measurement and :time keys in every map. The function Phoenix.LiveDashboard.extract_datapoint_for_metric/4 will return a map in exactly this format (with optional time argument if you want to override the default of System.system_time(:microsecond)), or it may return nil in which case the data point should not be saved.

More about telemetry

Now that you have metrics up and running, you can begin exploring the rest of the telemetry ecosystem! Here are a few links to get you started:

• The Telemetry.Metrics module documentation contains more information on:

  • Metric types
  • Breaking down metrics by tags
  • VM Metrics
  • Custom periodic polling

• For a deeper dive into Phoenix and Ecto metrics, see our Telemetry Walkthrough.

• For more Elixir libraries using :telemetry, see Libraries using Telemetry.

Configure Metrics

The LiveDashboard integrates with :telemetry converting each Telemetry.Metrics to a beautiful, real-time chart.

The following table shows how Telemetry.Metrics metrics map to LiveDashboard charts:

Telemetry.Metrics	Y-Axis Value(s)
last_value	Always set to an absolute value
counter	Always increased by 1
sum	Always increased/decreased by an absolute value
summary	Value/Min/Max/Avg
distribution	(Coming Soon) recording measurements in individual buckets

Reporter options

Reporter options can be given to each metric as an option. For example:

counter("my_app.counter", reporter_options: [...])

The following reporter options are available to the dashboard:

• :group - configures the group the metric belongs to. By default the group is the first part of the name. For example, counter("my_app.counter") defaults to group "my_app"

• :prune_threshold - the maximum number of data points. When the threshold is reached, the chart data will be pruned by half. Default is 1_000.