# Integration Guide - Adding ElixirDashboard to Your Phoenix App

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`:

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

Then run:

```bash
mix deps.get
```

### Step 2: Add to Supervision Tree

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

```elixir
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):

```elixir
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:

```elixir
# 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:

```elixir
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:

```bash
mix phx.server
```

Then visit:
- **Slow Endpoints:** http://localhost:4000/dev/performance/endpoints
- **Slow Queries:** http://localhost:4000/dev/performance/queries

## Advanced Usage

### Custom Layouts

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

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

### Programmatic Access

Access the performance data programmatically:

```elixir
# 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:

```elixir
# 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:

```elixir
# 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:

```elixir
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:

```elixir
# 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:

```elixir
# 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
```

```elixir
# 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
```

```elixir
# 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.