Integration Guide - Adding ElixirDashboard to Your Phoenix App

View Source

This guide shows you how to integrate ElixirDashboard into your existing Phoenix application as a library.

Installation

Step 1: Add Dependency

Add :elixir_dashboard to your mix.exs:

def deps do
  [
    {:elixir_dashboard, "~> 0.1.0"}
    # Or if using from a local path:
    # {:elixir_dashboard, path: "../elixir_dashboard"}
  ]
end

Then run:

mix deps.get

Step 2: Add to Supervision Tree

In lib/my_app/application.ex, add the Performance Monitor supervisor to your children:

defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    children = [
      # ... your existing children (Repo, PubSub, Endpoint, etc.)

      # Add ElixirDashboard PerformanceMonitor
      ElixirDashboard.PerformanceMonitor.Supervisor
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

Step 3: Attach Telemetry Handlers

Still in lib/my_app/application.ex, attach the telemetry handlers (recommended to do this only in development):

def start(_type, _args) do
  children = [
    # ... children list from above
  ]

  # Attach telemetry handlers only in development
  if Mix.env() == :dev do
    ElixirDashboard.PerformanceMonitor.TelemetryHandler.attach()
  end

  opts = [strategy: :one_for_one, name: MyApp.Supervisor]
  Supervisor.start_link(children, opts)
end

Step 4: Add Routes

In lib/my_app_web/router.ex, add routes for the performance dashboards:

# Only available in development
if Mix.env() == :dev do
  scope "/dev" do
    pipe_through :browser

    # ElixirDashboard routes
    live "/performance/endpoints", ElixirDashboard.PerformanceLive.Endpoints, :index
    live "/performance/queries", ElixirDashboard.PerformanceLive.Queries, :index
  end
end

Step 5: Configure (Optional)

In config/dev.exs, add configuration:

config :elixir_dashboard,
  # Maximum number of items to keep in memory for each category
  max_items: 100,
  # Endpoint duration threshold in milliseconds
  endpoint_threshold_ms: 100,
  # Query duration threshold in milliseconds
  query_threshold_ms: 50,
  # Auto-refresh interval in milliseconds
  refresh_interval_ms: 5000,
  # List of Ecto repo telemetry prefixes to monitor
  # Format: [[:app_name, :repo_name]]
  repo_prefixes: [[:my_app, :repo]]

Important: Make sure to configure repo_prefixes to match your actual Ecto repo module name(s).

For example:

  • If your repo is MyApp.Repo, use [[:my_app, :repo]]
  • If you have multiple repos: [[:my_app, :repo], [:my_app, :read_repo]]

That's It!

Start your Phoenix server:

mix phx.server

Then visit:

Advanced Usage

Custom Layouts

You can use your app's layout for the dashboard LiveViews:

# In router.ex
live "/performance/endpoints", ElixirDashboard.PerformanceLive.Endpoints, :index,
  layout: {MyAppWeb.Layouts, :app}

Programmatic Access

Access the performance data programmatically:

# Get all slow endpoints
endpoints = ElixirDashboard.PerformanceMonitor.get_slow_endpoints()

# Get all slow queries
queries = ElixirDashboard.PerformanceMonitor.get_slow_queries()

# Clear all data
ElixirDashboard.PerformanceMonitor.clear_all()

Runtime Control

Attach/detach monitoring at runtime:

# Start monitoring
ElixirDashboard.PerformanceMonitor.attach()

# Stop monitoring
ElixirDashboard.PerformanceMonitor.detach()

Troubleshooting

No Query Data Appearing?

Make sure you've configured repo_prefixes correctly in your config. The prefix should match your Ecto repo module.

To find your repo's telemetry prefix:

# Your repo is probably something like:
defmodule MyApp.Repo do
  use Ecto.Repo,
    otp_app: :my_app,
    adapter: Ecto.Adapters.Postgres
end

# The telemetry prefix is: [:my_app, :repo]

Then in config/dev.exs:

config :elixir_dashboard,
  repo_prefixes: [[:my_app, :repo]]

Dashboard Not Showing Up?

  1. Make sure you're in development mode (MIX_ENV=dev)
  2. Verify the routes are added to your router
  3. Check that the supervisor was added to your application
  4. Ensure telemetry handlers are attached (check your logs)

Different Port?

If your app runs on a different port, adjust the URL accordingly:

# In config/dev.exs
config :my_app, MyAppWeb.Endpoint,
  http: [port: 4001]

# Then visit http://localhost:4001/dev/performance/endpoints

Example: Full Integration

Here's a complete example for a typical Phoenix 1.7 app:

# lib/my_app/application.ex
defmodule MyApp.Application do
  use Application

  @impl true
  def start(_type, _args) do
    children = [
      MyApp.Repo,
      {Phoenix.PubSub, name: MyApp.PubSub},
      # Add ElixirDashboard
      ElixirDashboard.PerformanceMonitor.Supervisor,
      MyAppWeb.Endpoint
    ]

    # Attach telemetry in dev
    if Mix.env() == :dev do
      ElixirDashboard.PerformanceMonitor.TelemetryHandler.attach()
    end

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end

  @impl true
  def config_change(changed, _new, removed) do
    MyAppWeb.Endpoint.config_change(changed, removed)
    :ok
  end
end
# lib/my_app_web/router.ex
defmodule MyAppWeb.Router do
  use MyAppWeb, :router

  pipeline :browser do
    plug :accepts, ["html"]
    plug :fetch_session
    plug :fetch_live_flash
    plug :put_root_layout, html: {MyAppWeb.Layouts, :root}
    plug :protect_from_forgery
    plug :put_secure_browser_headers
  end

  scope "/", MyAppWeb do
    pipe_through :browser

    get "/", PageController, :home
    # ... your other routes
  end

  # Dev-only routes
  if Mix.env() == :dev do
    scope "/dev" do
      pipe_through :browser

      # ElixirDashboard
      live "/performance/endpoints", ElixirDashboard.PerformanceLive.Endpoints, :index
      live "/performance/queries", ElixirDashboard.PerformanceLive.Queries, :index

      # Optional: Phoenix LiveDashboard
      import Phoenix.LiveDashboard.Router
      live_dashboard "/dashboard", metrics: MyAppWeb.Telemetry
    end
  end
end
# config/dev.exs
import Config

# ... your existing config ...

# ElixirDashboard configuration
config :elixir_dashboard,
  max_items: 100,
  endpoint_threshold_ms: 100,
  query_threshold_ms: 50,
  refresh_interval_ms: 5000,
  repo_prefixes: [[:my_app, :repo]]

That's it! You now have performance monitoring integrated into your Phoenix application.