View Source PhoenixProfiler (phoenix_profiler v0.2.1)
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
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
Installation
To start using the profiler, you will need the following steps:
- Add the
phoenix_profiler
dependency - Define a profiler on your supervision tree
- Enable the profiler on your Endpoint
- Configure LiveView
- Add the
PhoenixProfiler
plug - Mount the profiler on your LiveViews
- Add the profiler page on your LiveDashboard (optional)
1-add-the-phoenix_profiler-dependency
1. Add the phoenix_profiler dependency
Add phoenix_profiler to your mix.exs
:
{:phoenix_profiler, "~> 0.2.0"}
2-define-a-profiler-on-your-supervision-tree
2. Define a profiler on your supervision tree
You define a profiler on your main application's telemetry supervision
tree (usually in lib/my_app_web/telemetry.ex
):
children = [
{PhoenixProfiler, name: MyAppWeb.Profiler},
# :telemetry_poller, etc.
]
Note that the profiler must be running for data to be collected, so it must come before any Endpoint modules in your supervision tree.
The following options are available:
:name
- The name of the profiler server. This option is required.:request_sweep_interval
- How often to sweep the ETS table where the profiles are stored. Default is24h
in milliseconds.
3-enable-the-profiler-on-your-endpoint
3. 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
options:
# config/dev.exs
config :my_app, MyAppWeb.Endpoint,
phoenix_profiler: [server: MyAppWeb.Profiler]
All web configuration is done inside the :phoenix_profiler
key on the endpoint.
The following options are available:
:server
- The name of the profiler server. This option is required.:enable
- When set tofalse
, disables profiling by default. You can always enable profiling on a request viaenable/1
. Defaults totrue
.: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
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. 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):
# config/config.exs
config :my_app, MyAppWeb.Endpoint,
live_view: [signing_salt: "SECRET_SALT"]
5-add-the-phoenixprofiler-plug
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
):
if code_reloading? do
# plugs...
plug PhoenixProfiler
end
6-mount-the-profiler-on-your-liveviews
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
):
def live_view do
quote do
# use...
on_mount PhoenixProfiler
# view helpers...
end
end
Note the on_mount
macro requires LiveView 0.16+. For earlier versions,
see PhoenixProfiler.enable/1
.
This is all. Run mix phx.server
and observe the toolbar on your browser requests.
7-add-the-profiler-page-on-your-livedashboard-optional
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 to enjoy all the features of PhoenixProfiler.
Add the dashboard definition to the list of :additional_pages
on
the live_dashboard
macro
in your router (usually in lib/my_app_web/router.ex
):
live_dashboard "/dashboard",
additional_pages: [
_profiler: {PhoenixProfiler.Dashboard, []}
# additional pages...
]
troubleshooting
Troubleshooting
exception-raised-with-other-on_mount-hooks
Exception raised with other on_mount hooks
If after enabling the profiler, you see an error like the following:
** (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:
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.
Link to this section Summary
Functions
Returns all running PhoenixProfiler names. It is important to notice that no order is guaranteed.
Returns the child specification to start the profiler under a supervision tree.
Disables profiling on a given conn
or socket
.
Enables the profiler on a given conn
or connected socket
.
The callback for the mount stage of the LiveView lifecycle.
Resets the storage of the given profiler
.
Link to this section Functions
Returns all running PhoenixProfiler names. It is important to notice that no order is guaranteed.
Returns the child specification to start the profiler under a supervision tree.
Disables profiling on a given conn
or socket
.
examples
Examples
Within a Phoenix Controller (for example, on an update callback):
def update(conn, params) do
conn = PhoenixProfiler.disable(conn)
# code...
end
Within in a LiveView (for example, on a handle_event callback):
def handle_event("some-event", _, socket) do
socket = PhoenixProfiler.disable(socket)
# code...
end
Note that only for LiveView, if you invoke disable/1
on
the LiveView mount
callback, the profiler may not be
registered yet and it will not receive the disable message.
If you need on-demand profiling, it is recommended you
start with the profiler in a disabled state and enable it
after the LiveView has mounted.
Enables the profiler on a given conn
or connected socket
.
Normally you do not need to invoke this function manually. It is invoked
automatically by the PhoenixProfiler plug in the Endpoint when a
profiler is enabled. In LiveView v0.16+ it is invoked automatically when
you define on_mount PhoenixProfiler
on your LiveView.
This function will raise if the endpoint is not configured with a profiler, or if the configured profiler is not running. For LiveView specifically, this function also raises if the given socket is not connected.
example
Example
Within a Phoenix Controller (for example, on a show callback):
def show(conn, params) do
conn = PhoenixProfiler.enable(conn)
# code...
end
Within a LiveView (for example, on the mount callback):
def mount(params, session, socket) do
socket =
if connected?(socket) do
PhoenixProfiler.enable(socket)
else
socket
end
# code...
end
The callback for the mount stage of the LiveView lifecycle.
To enable live profiling, add the following on your LiveView:
on_mount PhoenixProfiler
Resets the storage of the given profiler
.