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:
- Add the telemetry dependencies
- Define your telemetry module
- 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 is1_000
.:bucket_size
- the unit width of each bucket. This option only applies todistribution
histograms. The default value is20
.
metrics-history
Metrics history
Metrics history can also be enabled via a custom configuration.