Unified Observability for Phoenix

“I found it ironic that the first thing you do to time series data is squash the timestamp. That’s how the name Timeless was born.” –Mark Cotner

Unified observability for Phoenix: persistent metrics, logs, and traces in LiveDashboard.

One dep, one child_spec, one router macro — you get:

• Metrics — TimelessMetrics stores telemetry metrics that survive restarts
• Logs — TimelessLogs captures and indexes Elixir Logger output
• Traces — TimelessTraces stores OpenTelemetry spans
• Dashboard — All three as LiveDashboard pages, plus built-in charts with history

Documentation

• Getting Started
• Configuration Reference
• Architecture
• Dashboard
• Metrics
• Demo Traffic Generator
• Production Deployment
• Interactive Demo Livebook

Installation

With Igniter (recommended)

Add the dependency to mix.exs:

{:timeless_phoenix, "~> 1.5"},
{:igniter, "~> 0.6", only: [:dev, :test], runtime: false}

Then run:

mix deps.get
mix igniter.install timeless_phoenix

This automatically:

1. Adds {TimelessPhoenix, ...} to your supervision tree
2. Configures OpenTelemetry to export spans to TimelessTraces
3. Adds import TimelessPhoenix.Router to your Phoenix router
4. Adds timeless_phoenix_dashboard "/dashboard" to your browser scope
5. Removes the default live_dashboard route (avoids live_session conflict)
6. Updates .formatter.exs

By default, metrics, logs, and traces are all persisted to disk under priv/observability. If you want logs and traces to stay in memory only for CI or ephemeral demo environments:

mix igniter.install timeless_phoenix --storage memory

HTTP Endpoints

To expose HTTP ingest/query endpoints for external tooling (Grafana, curl, etc.), use the --http flag to enable all three:

mix igniter.install timeless_phoenix --http

Or enable them individually:

mix igniter.install timeless_phoenix --http-metrics --http-logs

Default ports are 8428 (metrics), 9428 (logs), and 10428 (traces). Override with:

mix igniter.install timeless_phoenix --http --metrics-port 9090 --logs-port 3100 --traces-port 4318

Manual

Add the dependency to mix.exs:

{:timeless_phoenix, "~> 1.5"}

Add to your application’s supervision tree (lib/my_app/application.ex):

children = [
  # ... existing children ...
  {TimelessPhoenix, data_dir: "priv/observability"}
]

Add to your router (lib/my_app_web/router.ex):

import TimelessPhoenix.Router

scope "/" do
  pipe_through :browser
  timeless_phoenix_dashboard "/dashboard"
end

Configure OpenTelemetry to export spans (config/config.exs):

config :opentelemetry, traces_exporter: {TimelessTraces.Exporter, []}

Remove the default live_dashboard route from your router — it’s typically inside an if Application.compile_env(:my_app, :dev_routes) block. TimelessPhoenix provides its own dashboard at the same path, and having both causes a live_session conflict.

Add :timeless_phoenix to your .formatter.exs import_deps:

[import_deps: [:timeless_phoenix, ...]]

Configuration

Child spec options

Router macro options

timeless_phoenix_dashboard "/dashboard",
  name: :default,                              # TimelessPhoenix instance name
  metrics: MyApp.Telemetry,                    # custom metrics module
  download_path: "/timeless/downloads",        # backup download path
  live_dashboard: [csp_nonce_assign_key: :csp] # extra LiveDashboard opts

Manual LiveDashboard setup

If you need full control over the LiveDashboard configuration instead of using the macro:

import Phoenix.LiveDashboard.Router

forward "/timeless/downloads", TimelessMetricsDashboard.DownloadPlug,
  store: :tp_default_timeless

live_dashboard "/dashboard",
  metrics: MyApp.Telemetry,
  metrics_history: {TimelessPhoenix, :metrics_history, []},
  additional_pages: TimelessPhoenix.dashboard_pages()

Running in Production

The Igniter installer places timeless_phoenix_dashboard in a top-level browser scope so it’s available in all environments. To restrict access in production, add authentication.

Authentication

Pipeline-based auth (recommended)

Create an admin pipeline with your existing auth plugs:

pipeline :admin do
  plug :fetch_current_user
  plug :require_admin_user
end

scope "/" do
  pipe_through [:browser, :admin]
  timeless_phoenix_dashboard "/dashboard"
end

Basic HTTP auth

For a quick setup using environment variables:

pipeline :dashboard_auth do
  plug :admin_basic_auth
end

scope "/" do
  pipe_through [:browser, :dashboard_auth]
  timeless_phoenix_dashboard "/dashboard"
end

# In your router or a plug module:
defp admin_basic_auth(conn, _opts) do
  username = System.fetch_env!("DASHBOARD_USER")
  password = System.fetch_env!("DASHBOARD_PASS")
  Plug.BasicAuth.basic_auth(conn, username: username, password: password)
end

LiveView on_mount hook

For LiveView-level auth, pass on_mount through to LiveDashboard:

timeless_phoenix_dashboard "/dashboard",
  live_dashboard: [on_mount: [{MyAppWeb.AdminAuth, :ensure_admin, []}]]

WebSocket proxies

If your app is behind nginx or a reverse proxy, ensure WebSocket upgrades are allowed. LiveDashboard uses LiveView, which requires a WebSocket connection.

Nginx example:

location /dashboard {
    proxy_pass http://localhost:4000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Production data directory

In production, use a persistent path outside the release:

{TimelessPhoenix, data_dir: "/var/lib/my_app/observability"}

Or configure at runtime:

{TimelessPhoenix, data_dir: System.get_env("OBS_DATA_DIR", "/var/lib/my_app/observability")}

Data Retention

TimelessPhoenix ships with sensible defaults for embedded use. All three engines retain 7 days of data by default.

Customizing retention

Override via the :timeless_logs and :timeless_traces child spec options:

{TimelessPhoenix,
  data_dir: "priv/observability",
  timeless_logs: [
    retention_max_age: 30 * 86_400,       # 30 days
    retention_max_size: 1_073_741_824,     # 1 GB cap (nil = unlimited)
    retention_check_interval: 120_000      # check every 2 minutes
  ],
  timeless_traces: [
    retention_max_age: 14 * 86_400,        # 14 days
    retention_max_size: 512 * 1_048_576    # 512 MB cap
  ]}

For metrics, use the :timeless key:

{TimelessPhoenix,
  data_dir: "priv/observability",
  timeless: [
    raw_retention_seconds: 14 * 86_400,    # 14 days raw
    daily_retention_seconds: 180 * 86_400  # 180 days rolled up
  ]}

Setting retention_max_age to nil disables time-based retention. Setting retention_max_size to nil disables size-based retention (default).

Custom Metrics

The default metrics include VM, Phoenix, LiveView, TimelessMetrics, TimelessLogs, and TimelessTraces telemetry. To add your own:

defmodule MyApp.Telemetry do
  import Telemetry.Metrics

  def metrics do
    TimelessPhoenix.DefaultMetrics.all() ++ [
      counter("my_app.orders.created"),
      summary("my_app.checkout.duration", unit: {:native, :millisecond}),
      last_value("my_app.queue.depth")
    ]
  end
end

Then pass it to both the child spec and router:

# application.ex
{TimelessPhoenix, data_dir: "priv/observability", metrics: MyApp.Telemetry.metrics()}

# router.ex
timeless_phoenix_dashboard "/dashboard", metrics: MyApp.Telemetry