Settings View Source Configuring metrics

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

installing-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

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

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

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.

more-about-telemetry

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

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	Total number of events in individual buckets

reporter-options

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:

• :nav - 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.

• :bucket_size - the unit width of each bucket. This option only applies to distribution histograms. The default value is 20.

metrics-history

Metrics history

Metrics history can also be enabled via a custom configuration.