Getting Started

Copy Markdown View Source

TimelessPhoenix adds persistent metrics, logs, and traces to your Phoenix app with a single dependency. Everything shows up in LiveDashboard -- no external infrastructure required.

What you get

  • Metrics -- Telemetry metrics stored in TimelessMetrics (Gorilla + Zstd TSDB) that survive restarts
  • Logs -- All Logger output captured and indexed in TimelessLogs (SQLite + OpenZL compressed blocks)
  • Traces -- OpenTelemetry spans stored in TimelessTraces with automatic Phoenix + Bandit instrumentation
  • Dashboard -- All three as LiveDashboard pages with charts, search, and historical data

If you have Igniter installed:

mix igniter.install timeless_phoenix

This automatically:

  1. Adds {TimelessPhoenix, data_dir: "priv/observability"} 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. Updates .formatter.exs

By default, the installer configures disk-backed metrics, logs, and traces:

mix igniter.install timeless_phoenix

If you want ephemeral logs and traces for development or CI:

mix igniter.install timeless_phoenix --storage memory

Memory mode stores logs and traces in memory only (lost on restart). Metrics are still persisted to disk.

Manual installation

Add the dependency to mix.exs:

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

Add to your 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

If your router has a default LiveDashboard route (typically in a dev_routes block), remove it to avoid a live_session conflict.

Verify it's working

Start your application:

mix phx.server

Open http://localhost:4000/dashboard and you'll see:

  • Home -- Standard LiveDashboard with historical metrics charts
  • Timeless -- Metrics TSDB dashboard with compression stats and backups
  • Logs -- Searchable log viewer with level/time filtering
  • Traces -- Trace/span viewer with service, kind, and status filtering

Metrics, logs, and traces start populating immediately. Metrics persist across restarts in priv/observability/metrics/, and if using disk storage, logs and traces persist in logs/ and spans/ respectively.

Generate demo traffic

To populate the dashboards with interesting data:

mix timeless_phoenix.gen_demo

This creates a GenServer that simulates HTTP requests, database queries, background jobs, cache operations, warnings, and errors every 2 seconds. See the Demo Traffic guide for details.

Interactive demo

For a hands-on walkthrough without a Phoenix app, open the demo livebook in Livebook. It starts all three engines, generates data, renders inline SVG charts, and shows compression stats interactively.

Next steps