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

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

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: {MyModule, :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

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 MyHeaderScrubber 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: &MyHeaderScrubber.scrub_headers/1

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

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

scrubbing-cookies

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: &MyCookieScrubber.scrub_cookies/1

including-request-identifiers

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

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.