TelemetryUI

A complete TelemetryUI configuration is a list containing three main keys: metrics, theme, and backend.

Metrics

metrics is a list of tuples. Each tuple represents a page (metrics group) and follows the format: {"Page Name", metrics_list, ui_options: [...]}.

Each metrics_list is composed of individual metric definitions (e.g., counter/2, average/2, distribution/2) imported from TelemetryUI.Metrics.

Theme

A map defining the visual appearance of the UI, including header_color, primary_color, title, share_key, and logo (SVG string).

Backend

A map or struct defining how data is stored and managed (e.g., %TelemetryUI.Backend.EctoPostgres{...}).

defmodule MyApp.TelemetryUI do
  import TelemetryUI.Metrics

  def config do
    ui_options = [metrics_class: "grid-cols-8 gap-4"]

    [
      metrics: [
        {"HTTP", http_metrics(), ui_options: ui_options},
        {"System", system_metrics()}
      ],
      theme: theme(),
      backend: backend()
    ]
  end

  # ... helper functions for metrics, theme, and backend
end

The configuration passed to {TelemetryUI, config} is a keyword list. Use these options to define your metrics, storage backend, and UI appearance.

Required Options

:metrics

Defines the metrics to display. You can use three formats:

1. Simple list: All metrics appear on one unnamed page.
2. Named pages (2-tuple): { "Page Title", [metrics] } groups metrics into titled pages.
3. Named pages with UI options (3-tuple): { "Page Title", [metrics], ui_options: [...] } allows page-level customization like grid layouts or visibility.

Optional Options

• :backend: Configures storage. If omitted, metrics are not persisted. Currently, only EctoPostgres is supported.
• :theme: A map of customization options for the UI (see Theme Options).
• :name: An atom identifier (e.g., :admin). Required if running multiple TelemetryUI instances.
• :config: A function or module/function tuple used for dynamic configuration to enable hot-reloading.

metrics: [
  counter("phoenix.router_dispatch.stop.duration"),
  {"HTTP", [counter("phoenix.router_dispatch.stop.duration")]},
  {"HTTP", http_metrics(), ui_options: [metrics_class: "grid-cols-4 gap-4"]}
]

# Dynamic config
config: {MyApp.Telemetry, :config}
config: fn -> MyApp.Telemetry.config() end

You can control the layout of metrics using TailwindCSS classes. There are two levels of layout control:

1. Individual Metric Layout: Use the ui_options: [class: "..."] key within a metric definition (like distribution/2) to apply classes to that specific metric's container.
2. Metrics Container Layout: Use the ui_options: [metrics_class: "..."] key within the metrics list definition to apply classes to the container holding the metrics (e.g., to define a grid structure).

All Tailwind grid classes are supported, including sm and lg variants for responsive mobile and desktop views.

metrics = [
  distribution("my_app.repo.query.total_time",
    reporter_options: [buckets: [0, 4, 10, 50]],
    ui_options: [class: "col-span-2"],
    unit: {:native, :millisecond}
  ),
  distribution("phoenix.router_dispatch.stop.duration",
    reporter_options: [buckets: [0, 40, 100, 500]],
    ui_options: [class: "col-span-2"],
    unit: {:native, :millisecond}
  ),
  distribution("phoenix.router_dispatch.stop.duration",
    tags: [:route],
    reporter_options: [buckets: [0, 40, 100, 500]],
    ui_options: [class: "col-span-full"],
    unit: {:native, :millisecond}
  )
]

[
  metrics: [
    {"Metrics layout page", metrics, ui_options: [metrics_class: "grid-cols-4 gap-4"]}
  ],
  backend: #...
  theme: #...
]

You can expose different sets of metrics at different URL paths by using the telemetry_ui_name key in your Plug.Conn assigns. This allows you to control access to specific metrics dashboards using your application's existing routing and authentication logic (e.g., via pipe_through).

To implement this:

1. Define multiple routes in your router, each passing a unique :telemetry_ui_name in the assigns option.
2. Create corresponding configuration functions in your Telemetry module that return metric definitions matching those names.
3. Start a separate TelemetryUI process for each configuration in your application supervisor.

# 1. Router configuration
scope "/admin" do
  pipe_through [EnsureAdmin]
  get("/metrics", TelemetryUI.Web, :index, assigns: %{telemetry_ui_name: :admin})
end

scope "/user_dashboard" do
  pipe_through [EnsureUser]
  get("/metrics", TelemetryUI.Web, :index, assigns: %{telemetry_ui_name: :user_dashboard})
end

# 2. Telemetry module definitions
defmodule MyApp.Telemetry do
  import TelemetryUI.Metrics

  def admin do
    [
      name: :admin,
      metrics: [
        {"Memory", [value_over_time("vm.memory.total", unit: {:byte, :megabyte})]}
      ],
      backend: backend(),
      theme: %{header_color: "purple", title: "Admin metrics"}
    ]
  end

  def user_dashboard do
    [
      name: :user_dashboard,
      metrics: [
        {"Followers", [count_over_time("myapp.users.new_follower")]}
      ],
      backend: backend(),
      theme: %{header_color: "blue", title: "User dashboard metrics"}
    ]
  end
end

You can display existing application metrics (like database counts) in telemetry_ui without using the telemetry package by using the data_resolver option.

To do this, provide a function to data_resolver that accepts an options argument (containing :from and :to timestamps) and returns {:ok, data}. The returned data should follow the same format used by telemetry_ui_events to ensure consistent graph layouts.

For a count-over-time metric, the resolver should return a list of maps where each map contains a :date and a :count key.

count_over_time(:data,
  description: "Users count",
  unit: " users",
  data_resolver: fn options ->
    query =
      from(
        users in "users",
        select: %{date: users.inserted_at, count: 1},
        where: users.inserted_at >= ^options.from and users.inserted_at <= ^options.to
      )

    {:ok, MyApp.Repo.all(query)}
  end
)