Configuration Reference

View Source

This guide provides a comprehensive reference for all TelemetryUI configuration options.

Top-Level Configuration

The configuration passed to {TelemetryUI, config} is a keyword list with the following options:

Required Options

:metrics

List of metrics to display. Can be specified in three formats:

  1. Simple list - All metrics in a single unnamed page:

    metrics: [
  counter("phoenix.router_dispatch.stop.duration"),
  last_value("vm.memory.total")
]

  2. Named pages (2-tuple) - Group metrics into pages with titles:

    metrics: [
  {"HTTP", [counter("phoenix.router_dispatch.stop.duration")]},
  {"System", [last_value("vm.memory.total")]}
]

  3. Named pages with UI options (3-tuple) - Add page-level customization:

    metrics: [
  {"HTTP", http_metrics(), ui_options: [metrics_class: "grid-cols-4 gap-4"]},
  {"Debug", debug_metrics(), ui_options: [hidden: true]}
]

Optional Options

:backend

Backend storage configuration. Currently only EctoPostgres is supported:

backend: %TelemetryUI.Backend.EctoPostgres{
  repo: MyApp.Repo,
  pruner_threshold: [months: -1],
  pruner_interval_ms: 84_000,
  max_buffer_size: 10_000,
  flush_interval_ms: 10_000,
  insert_date_bin: Duration.new!(minute: 5),
  verbose: false,
  telemetry_prefix: [:telemetry_ui, :repo],
  telemetry_options: [telemetry_ui_conf: []]
}

If not provided, metrics will not be persisted.

:theme

Customization options for the UI. See Theme Options below.

:name

Atom identifier for the TelemetryUI instance. Required when running multiple instances:

name: :admin

Default: :default

:config

Function reference for dynamic configuration (enables hot-reloading):

# Module and function tuple
config: {MyApp.Telemetry, :config}

# Anonymous function
config: fn -> MyApp.Telemetry.config() end

Backend Options

EctoPostgres Backend

:repo (required)

Your application's Ecto repository module:

repo: MyApp.Repo

:pruner_threshold

How long to keep historical data. Uses Elixir's date arithmetic:

pruner_threshold: [months: -1]   # Keep 1 month of data
pruner_threshold: [days: -7]     # Keep 7 days of data
pruner_threshold: [weeks: -4]    # Keep 4 weeks of data

Default: [months: -1]

:pruner_interval_ms

How often to run the pruner (in milliseconds):

pruner_interval_ms: 84_000       # Every 84 seconds
pruner_interval_ms: 3_600_000    # Every hour

Set to nil to disable automatic pruning.

Default: 84_000 (84 seconds)

:max_buffer_size

Maximum number of events to buffer before flushing to database:

max_buffer_size: 10_000

Default: 10_000

:flush_interval_ms

How often to flush buffered events to database (in milliseconds):

flush_interval_ms: 10_000   # Flush every 10 seconds

Default: 10_000

:insert_date_bin

Time bin size for aggregating events. Uses Elixir's Duration struct:

insert_date_bin: Duration.new!(minute: 5)    # 5-minute bins
insert_date_bin: Duration.new!(minute: 1)    # 1-minute bins
insert_date_bin: Duration.new!(second: 30)   # 30-second bins

Smaller bins = more granular data but more database rows.

Default: Duration.new!(minute: 5)

:verbose

Enable detailed logging for database operations:

verbose: true

Default: false

:telemetry_prefix

Telemetry event prefix for backend operations:

telemetry_prefix: [:telemetry_ui, :repo]

Default: [:telemetry_ui, :repo]

:telemetry_options

Additional options passed to telemetry events:

telemetry_options: [telemetry_ui_conf: []]

Default: [telemetry_ui_conf: []]

Theme Options

Customize the appearance of your metrics dashboard:

:primary_color

Primary color used for the title and first color in charts. Accepts CSS color values:

primary_color: "#3F84E5"
primary_color: "rgb(63, 132, 229)"
primary_color: "blue"

Default: "#3F84E5"

:header_color

Color used for text in the header:

header_color: "#28cb87"

Default: Same as :primary_color

:title

Title displayed in the header and HTML page title:

title: "My App Metrics"

Default: "/metrics"

:description

HTML meta description tag:

description: "HTTP, GraphQL and Database metrics"

Default: "Metrics"

SVG logo as a string, used for favicon and header:

logo: """
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 16 16">
  <circle cx="8" cy="8" r="8" fill="currentColor"/>
</svg>
"""

Default: TelemetryUI's default logo

:scale

List of hex colors used in charts. Colors are used in order:

scale: ["#3F84E5", "#7EB26D", "#EAB839", "#6ED0E0"]

Default: TelemetryUI's built-in color palette (48 colors)

:share_key

16-character string to enable shareable metrics pages:

share_key: "abc123def456ghi7"  # Exactly 16 characters

Set to nil to disable sharing feature.

Default: nil

:share_path

URL path for the shareable metrics page:

share_path: "/metrics/public"

Must be registered in your router with TelemetryUI.Web.Share.

Default: nil

:frame_options

Time frame options in the UI selector:

frame_options: [
  {:last_30_minutes, 30, :minute},
  {:last_2_hours, 120, :minute},
  {:last_1_day, 1, :day},
  {:last_7_days, 7, :day},
  {:last_1_month, 1, :month},
  {:custom, 0, nil}
]

Format: {identifier_atom, number, time_unit}

Default: Last 30 minutes, 2 hours, 1 day, 7 days, 1 month, and custom

Page UI Options

When defining metrics pages with the 3-tuple format, you can pass ui_options:

{"Page Title", metrics, ui_options: [key: value]}

:metrics_class

TailwindCSS grid classes for metrics layout:

ui_options: [metrics_class: "grid-cols-4 gap-4"]
ui_options: [metrics_class: "grid-cols-1 md:grid-cols-3 lg:grid-cols-6 gap-2"]

Supports all Tailwind responsive variants (sm:, md:, lg:).

Default: "grid-cols-1 md:grid-cols-3 gap-4"

:hidden

Hide the page from navigation and main view:

ui_options: [hidden: true]

Useful for internal metrics or debugging pages.

Default: false

:styles

Custom CSS styles applied to the page container:

ui_options: [styles: "background-color: #f0f0f0; padding: 20px;"]

Default: ""

Metric Options

Each metric function supports various options. Common options include:

:description

Human-readable description shown in the UI:

counter("phoenix.router_dispatch.stop.duration",
  description: "Total number of HTTP requests"
)

:unit

Unit conversion for measurements:

unit: {:native, :millisecond}      # Convert native time to ms
unit: {:byte, :megabyte}           # Convert bytes to MB
unit: {:byte, :gigabyte}           # Convert bytes to GB

:ui_options

UI customization per metric:

ui_options: [
  unit: " requests",                    # Suffix for displayed values
  class: "col-span-2"                   # TailwindCSS classes
]

:keep

Filter function to include/exclude events:

keep: fn metadata ->
  metadata[:route] not in ~w(/metrics /health)
end

:tags

Additional tag dimensions for grouping:

tags: [:route]
tags: [:route, :method]

:tag_values

Custom function to extract tag values:

tag_values: fn metadata ->
  %{custom_tag: extract_custom_value(metadata)}
end

:reporter_options

Options passed to the metric reporter:

reporter_options: [
  buckets: [0, 100, 500, 2000]    # For distributions
]

:data_resolver

Custom function for providing data (instead of telemetry events):

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

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

See guides/application-data.md for more details.

Application-Level Configuration

Set in config/config.exs or environment-specific configs:

:disabled

Disable all TelemetryUI processes:

# config/test.exs
config :telemetry_ui, disabled: true

Useful for testing environments.

Default: false

Complete Example

[
  # Instance name (for multiple dashboards)
  name: :admin,

  # Metrics configuration
  metrics: [
    {"HTTP", http_metrics(), ui_options: [metrics_class: "grid-cols-4 gap-4"]},
    {"Database", db_metrics(), ui_options: [metrics_class: "grid-cols-2"]},
    {"Internal", internal_metrics(), ui_options: [hidden: true]}
  ],

  # Backend storage
  backend: %TelemetryUI.Backend.EctoPostgres{
    repo: MyApp.Repo,
    pruner_threshold: [months: -1],
    pruner_interval_ms: 3_600_000,
    max_buffer_size: 10_000,
    flush_interval_ms: 10_000,
    insert_date_bin: Duration.new!(minute: 5),
    verbose: false
  },

  # Theme customization
  theme: %{
    primary_color: "#3F84E5",
    header_color: "#3F84E5",
    title: "Admin Metrics Dashboard",
    description: "Real-time application metrics",
    logo: "<svg>...</svg>",
    scale: ["#3F84E5", "#7EB26D", "#EAB839"],
    share_key: "abc123def456ghi7",
    share_path: "/metrics/admin/share",
    frame_options: [
      {:last_hour, 60, :minute},
      {:last_day, 1, :day},
      {:last_week, 7, :day}
    ]
  }
]

See Also