Plug v1.6.1 Plug.Debugger View Source
A module (not a plug) for debugging in development.
This module is commonly used within a Plug.Builder
or a Plug.Router
and it wraps the call/2
function.
Notice Plug.Debugger
does not catch errors, as errors should still
propagate so that the Elixir process finishes with the proper reason.
This module does not perform any logging either, as all logging is done
by the web server handler.
Note: If this module is used with Plug.ErrorHandler
, only one of
them will effectively handle errors. For this reason, it is recommended
that Plug.Debugger
is used before Plug.ErrorHandler
and only in
particular environments, like :dev
.
Examples
defmodule MyApp do
use Plug.Builder
if Mix.env == :dev do
use Plug.Debugger, otp_app: :my_app
end
plug :boom
def boom(conn, _) do
# Error raised here will be caught and displayed in a debug page
# complete with a stacktrace and other helpful info.
raise "oops"
end
end
Options
:otp_app
- the OTP application that is using Plug. This option is used to filter stacktraces that belong only to the given application.:style
- custom styles (see below):banner
- the optional MFA ({module, function, args}
) which receives exception details and returns banner contents to appear at the top of the page. May be any string, including markup.
Custom styles
You may pass a :style
option to customize the look of the HTML page.
use Plug.Debugger, style:
[primary: "#c0392b", logo: "data:image/png;base64,..."]
The following keys are available:
:primary
- primary color:accent
- accent color:logo
- logo URI, ornil
to disable
The :logo
is preferred to be a base64-encoded data URI so not to make any
external requests, though external URLs (eg, https://...
) are supported.
Custom Banners
You may pass an MFA ({module, function, args}
) to be invoked when an
error is rendered which provides a custom banner at the top of the
debugger page. The function receives the following arguments, with the
passed args
concentated at the end:
[conn, status, kind, reason, stacktrace]
For example, the following :banner
option:
use Plug.Debugger, banner: {MyModule, :debug_banner, []}
would invoke the function:
MyModule.debug_banner(conn, status, kind, reason, stacktrace)
Links to the text editor
If a PLUG_EDITOR
environment variable is set, Plug.Debugger
will
use it to generate links to your text editor. The variable should be
set with __FILE__
and __LINE__
placeholders which will be correctly
replaced. For example (with the TextMate editor):
txmt://open/?url=file://__FILE__&line=__LINE__