A Plug for adding request context to Sentry events.

This module adds Sentry context metadata during the request in a Plug application. It includes defaults for scrubbing sensitive data, and options for customizing such behavior.

Usage

You can use this module in a Plug pipeline to add Sentry metadata:

plug Sentry.PlugContext

However, this module is generally intended to be used with Sentry.PlugCapture: this plug will add context metadata to the request, while Sentry.PlugCapture will capture raised exceptions and errors and report them to Sentry with the added metadata.

Scrubbing POST Body Params

In order to send POST body parameters you should first scrub them of sensitive information. By default, they will be scrubbed with default_body_scrubber/1. This can be overridden by passing the :body_scrubber option, which accepts a Plug.Conn and returns a map to send. Setting :body_scrubber to nil will not send any data back. If you would like to make use of Sentry's default scrubber behavior in a custom scrubber, it can be called directly. An example configuration may look like the following:

defmodule MySentryScrubber do
  def scrub_params(conn) do
    # Makes use of the default body_scrubber to avoid sending password
    # and credit card information in plain text. To also prevent sending
    # our sensitive "my_secret_field" and "other_sensitive_data" fields,
    # we simply drop those keys.
    conn
    |> Sentry.PlugContext.default_body_scrubber()
    |> Map.drop(["my_secret_field", "other_sensitive_data"])
  end
end

Then pass it into Sentry.PlugContext:

plug Sentry.PlugContext, body_scrubber: &MySentryScrubber.scrub_params/1

You can also pass it in as a {module, fun}, like so:

plug Sentry.PlugContext, body_scrubber: {MySentryScrubber, :scrub_params}

Large Files

If you are sending large files in POST requests, we recommend you scrub them out through the :body_scrubber mechanism.

Scrubbing Headers

By default, Sentry uses default_header_scrubber/1 to scrub headers. This can be configured similarly to body params, through the :header_scrubber configuration option:

defmodule MySentryScrubber do
  def scrub_headers(conn) do
    # In this example, we do not want to include Content-Type or User-Agent
    # in reported headers, so we drop them.
    conn.req_headers
    |> Map.new()
    |> Sentry.PlugContext.default_header_scrubber()
    |> Map.drop(["content-type", "user-agent"])
  end
end

Then, pass it into Sentry.PlugContext:

plug Sentry.PlugContext, header_scrubber: &MySentryScrubber.scrub_headers/1

It can also be passed in as a {module, fun} like so:

plug Sentry.PlugContext, header_scrubber: {MySentryScrubber, :scrub_headers}

Scrubbing Cookies

By default Sentry will scrub all cookies before sending events (see scrub_cookies/1). It can be configured similarly to the headers and body scrubbers, but is configured via the :cookie_scrubber key.

For example:

plug Sentry.PlugContext, cookie_scrubber: &MySentryScrubber.scrub_cookies/1

Scrubbing URLs

Available since v10.2.0.

If any of your URLs contain sensitive tokens or other data, you should scrub them to remove the sensitive data. This can be configured similarly to body params, through the :url_scrubber configuration option. It should return a string:

defmodule MySentryScrubber do
  def scrub_url(conn) do
    conn
    |> Plug.Conn.request_url()
    |> String.replace(~r/secret-token/w+/, "secret-token/****")
  end
end

Then pass it into Sentry.PlugContext:

plug Sentry.PlugContext, url_scrubber: &MySentryScrubber.scrub_url/1

You can also pass it in as a {module, fun}, like so:

plug Sentry.PlugContext, url_scrubber: {MySentryScrubber, :scrub_url}

Including Request Identifiers

If you're using Phoenix, Plug.RequestId, or any other method to set a request ID response header, and would like to include that information with errors reported by Sentry.PlugContext, use the :request_id_header option. It allows you to set which header key Sentry should check. It defaults to x-request-id, which Plug.RequestId (and therefore Phoenix) also default to.

plug Sentry.PlugContext, request_id_header: "application-request-id"

Remote Address Reader

Sentry.PlugContext includes a request's originating IP address under the REMOTE_ADDR environment key in Sentry. By default, we read it from the x-forwarded-for HTTP header, and if this header is not present, from conn.remote_ip.

If you wish to read this value differently (for example, from a different HTTP header), or modify it in some other way (such as by masking it), you can configure this behavior by passing the :remote_address_reader option:

plug Sentry.PlugContext, remote_address_reader: &MyModule.read_ip/1

The :remote_address_reader option must be a function that accepts a Plug.Conn returns a String.t/0 IP, or a {module, function} tuple, where module.function/1 takes a Plug.Conn and returns a String.t/0 IP.