Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mcrumm/phoenix_profiler

Web Profiler and Debug Toolbar for Phoenix Framework
https://github.com/mcrumm/phoenix_profiler

dashboard debug elixir phoenix phoenix-framework telemetry toolbar

Last synced: 7 days ago
JSON representation

Web Profiler and Debug Toolbar for Phoenix Framework

Host: GitHub
URL: https://github.com/mcrumm/phoenix_profiler
Owner: mcrumm
License: mit
Created: 2021-09-30T22:13:15.000Z (about 3 years ago)
Default Branch: main
Last Pushed: 2023-07-12T23:11:49.000Z (over 1 year ago)
Last Synced: 2024-04-14T05:51:49.551Z (7 months ago)
Topics: dashboard, debug, elixir, phoenix, phoenix-framework, telemetry, toolbar
Language: Elixir
Homepage:
Size: 492 KB
Stars: 190
Watchers: 9
Forks: 5
Open Issues: 7
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

# PhoenixProfiler

Provides a **development tool** that gives detailed information about the execution of any request.

**Never** enable it on production servers as it exposes sensitive data about your web application.

## Built-in Features

* Request/Response - status code, params, headers, cookies, etc.

* Routing - endpoint, router, controller/live view, action, etc.

* Basic diagnostics - response time, memory

* Inspect LiveView crashes

* Inspect Ecto queries (Coming Soon)

* Swoosh mailer integration (Coming Soon)

## Installation

To start using the profiler, you will need the following steps:

1. Add the `phoenix_profiler` dependency
2. Enable the profiler on your Endpoint
3. Configure LiveView
4. Add the `PhoenixProfiler` plug
5. Mount the profiler on your LiveViews
6. Add the profiler page on your LiveDashboard (optional)

### 1. Add the phoenix_profiler dependency

Add phoenix_profiler to your `mix.exs`:

```elixir
{:phoenix_profiler, "~> 0.2.0"}
```

### 2. Enable the profiler on your Endpoint

PhoenixProfiler is disabled by default. In order to enable it,
you must update your endpoint's `:dev` configuration to include the
`:phoenix_profiler` option:

```elixir
# config/dev.exs
config :my_app, MyAppWeb.Endpoint,
phoenix_profiler: []
```

All web configuration is done inside the `:phoenix_profiler` key on the endpoint.

The following options are available:

* `:enable` - When set to `false`, disables profiling by default. You can
always enable profiling on a request via `enable/1`. Defaults to `true`.

* `:profiler_link_base` - The base path for generating links
on the toolbar. Defaults to `"/dashboard/_profiler"`.

* `:toolbar_attrs` - HTML attributes to be given to the element
injected for the toolbar. Expects a keyword list of atom keys and
string values. Defaults to `[]`.

### 4. Configure LiveView

> If LiveView is already installed in your app, you may skip this section.

The Phoenix Web Debug Toolbar is built on top of LiveView. If you plan to use LiveView in your application in the future we recommend you follow [the official installation instructions](https://hexdocs.pm/phoenix_live_view/installation.html).
This guide only covers the minimum steps necessary for the toolbar itself to run.

Update your endpoint's configuration to include a signing salt. You can generate a signing salt by running `mix phx.gen.secret 32` (note Phoenix v1.5+ apps already have this configuration):

```elixir
# config/config.exs
config :my_app, MyAppWeb.Endpoint,
live_view: [signing_salt: "SECRET_SALT"]
```

### 5. Add the PhoenixProfiler plug

Add the `PhoenixProfiler` plug within the `code_reloading?`
block on your Endpoint (usually in `lib/my_app_web/endpoint.ex`):

```elixir
if code_reloading? do
# plugs...
plug PhoenixProfiler
end
```

### 6. Mount the profiler on your LiveViews

Note this section is required only if you are using LiveView, otherwise you may skip it.

Add the profiler hook to the `live_view` function on your
web module (usually in `lib/my_app_web.ex`):

```elixir
def live_view do
quote do
# use...

on_mount PhoenixProfiler

# view helpers...
end
end
```

This is all. Run `mix phx.server` and observe the toolbar on your browser requests.

### 7. Add the profiler page on your LiveDashboard (optional)

Note this section is required for the LiveDashboard integration. If you are
not using LiveDashboard, you may technically skip this step, although it is
highly recommended that you
[install LiveDashboard](https://hexdocs.pm/phoenix_live_dashboard/Phoenix.LiveDashboard.html#module-installation)
to enjoy all the features of PhoenixProfiler.

Add the dashboard definition to the list of `:additional_pages` on
the [`live_dashboard`](`Phoenix.LiveDashboard.Router.live_dashboard/2`) macro
in your router (usually in `lib/my_app_web/router.ex`):

```elixir
live_dashboard "/dashboard",
additional_pages: [
_profiler: {PhoenixProfiler.Dashboard, []}
# additional pages...
]
```

## Troubleshooting

### Exception raised with other on_mount hooks

If after enabling the profiler, you see an error like the
following:

```elixir
** (exit) an exception was raised:
** (RuntimeError) cannot attach hook with id :active_tab on :handle_params because the view was not mounted at the router with the live/3 macro
```

Then you need to add an extra clause on your `on_mount/4` function:

```elixir
def on_mount(_arg, :not_mounted_at_router, _session, socket) do
{:cont, socket}
end
```

This is true for any handle_params hooks that will be invoked
for LiveView modules not mounted at the router (i.e. via
live_render/3), and the web debug toolbar is no exception.

## Contributing

For those planning to contribute to this project, you can run a dev app with the following commands:

$ mix setup
$ mix dev

Alternatively, run `iex -S mix dev` if you also want a shell.

## License