View Source Sentry.PlugCapture (Sentry v14.0.0)

Ensures proper error reporting for Plug applications that use Cowboy.

It is intended for usage with Sentry.PlugContext, which adds relevant request metadata to the Sentry context before errors are captured.

Only for Cowboy

Sentry.PlugCapture is only recommended for Cowboy applications. For applications running on Bandit, which is the most recent default webserver in Phoenix, Sentry.PlugContext should be enough, and using Sentry.PlugCapture might result in duplicate errors.

Usage

With Phoenix

In a Phoenix application, it is important to use this module before the Phoenix endpoint itself. It should be added to your endpoint.ex file:

defmodule MyApp.Endpoint
  use Sentry.PlugCapture
  use Phoenix.Endpoint, otp_app: :my_app

  # ...
end

With Plug

In a Plug application, you can add this module below your router:

defmodule MyApp.PlugRouter do
  use Plug.Router
  use Sentry.PlugCapture

  # ...
end

use Sentry.PlugCapture

When you use Sentry.PlugCapture, Sentry overrides your Plug.call/2 callback and adds capturing errors and reporting to Sentry. You can still re-override that callback after use Sentry.PlugCapture if you need to.

Scrubbing Sensitive Data

Since v9.1.0

Scrubbing sensitive data in Sentry.PlugCapture is available since v9.1.0 of this library.

Like Sentry.PlugContext, this module also supports scrubbing sensitive data out of errors. However, this module has to do some guessing to figure out if there are Plug.Conn structs to scrub. Right now, the strategy we use follows these steps:

1. if the error is Phoenix.ActionClauseError, we scrub the Plug.Conn in the args field of that exception, and mirror that conn's scrubbed params onto the action's standalone params argument so both are redacted consistently

Scrubbing goes through the same Sentry.Scrubber implementation as Sentry.PlugContext, so it honors the per-field scrubbers (:body_scrubber, :header_scrubber, :cookie_scrubber, :url_scrubber) configured on Sentry.PlugContext for the current request.

Otherwise, we don't perform any scrubbing. To configure scrubbing, you can use the :scrubber option (see below).

Options

• :scrubber (since v9.1.0) - a term of type {module, function, args} that will be invoked to scrub sensitive data from Plug.Conn structs. The Plug.Conn struct is prepended to args before invoking the function, so that the final function will be called as apply(module, function, [conn | args]). The function must return a Plug.Conn struct; if it returns anything else, or if it crashes, scrubbing falls back to the built-in scrubber (see Crashing Callbacks below). By default, the built-in scrubber delegates to Sentry.Scrubber.scrub/1, which honors any :body_scrubber, :header_scrubber, :cookie_scrubber, or :url_scrubber opts configured on Sentry.PlugContext for the current request. When no Sentry.PlugContext has run, falls back to the defaults defined by Sentry.Scrubber.scrub/2:

  • scrubs all cookies (cookies and req_cookies)
  • drops sensitive request headers (authorization, authentication, cookie)
  • scrubs params and body_params through the configured body_scrubber (defaulting to the sensitive params in Sentry.Scrubber.default_param_keys/0; a nil body_scrubber empties both), and scrubs the same sensitive params in query_params and path_params
  • derives request_path, path_info and query_string from the URL the configured url_scrubber returns, so a scrubber that redacts a path segment redacts it here too; query_string is scrubbed against the sensitive params either way
  • clears assigns (where auth libraries store user structs and tokens)
  • reduces private to an allow-list of framework metadata, dropping everything else (notably the decoded session under :plug_session); configurable via the scrubber: [conn_private_allow_list: ...] option

Crashing Callbacks

Available since 14.0.0.

If anything in the capture path raises, throws, or exits - the :scrubber callback, the scrubbing of the exception, or the reporting itself - this module still re-raises the application's original exception, unchanged. Only the reporting degrades, and only as far as the failure forces:

See the Crashing Callbacks section of the Sentry documentation for how the failure is logged and why a crashed scrubber sends data that only it was dropping.