Sentry
Sentry
v9.1.0

View Source Sentry.LoggerHandler (Sentry v9.1.0)

:logger handler to report logged events to Sentry.

This module is similar to Sentry.LoggerBackend, but it implements a :logger handler rather than an Elixir's Logger backend.

This module is available since v9.0.0 of this library.

When to Use the Handler vs the Backend?

There is no functional difference in behavior between Sentry.LoggerHandler and Sentry.LoggerBackend when it comes to reporting to Sentry. The main functional difference is that Sentry.LoggerBackend runs in its own process, while Sentry.LoggerHandler runs in the process that logs. The latter is generally preferable.

The reason both exist is that :logger handlers are a relatively-new feature in Erlang/OTP, and Sentry.LoggerBackend was created before :logger handlers were introduced.

In general, try to use Sentry.LoggerHandler if possible. In future Elixir releases, Logger backends may become deprecated and hence Sentry.LoggerBackend may be eventually removed.

crash-reports

 Crash Reports

The reason you'll want to add this handler to your application is so that you can report crashes in your system to Sentry. Sometimes, you're able to catch exceptions and handle them (such as reporting them to Sentry), which is what you can do with Sentry.PlugCapture for example.

However, Erlang/OTP systems are made of processes running concurrently, and sometimes those processes crash and exit. If you're not explicitly catching exceptions in those processes to report them to Sentry, then you won't see those crash reports in Sentry. That's where this handler comes in. This handler hooks into :logger and reports nicely-formatted crash reports to Sentry.

usage

 Usage

To add this handler to your system, see the documentation for handlers in Elixir.

You can configure this handler in the :logger key under your application's configuration, potentially alongside other :logger handlers:

config :my_app, :logger, [
  {:handler, :my_sentry_handler, Sentry.LoggerHandler, %{
    config: %{metadata: [:file, :line]}
  }}
]

If you do this, then you'll want to add this to your application's Application.start/2 callback, similarly to what you would do with Sentry.LoggerBackend and the call to Logger.add_backend/1:

def start(_type, _args) do
  Logger.add_handlers(:my_app)

  # ...
end

Alternatively, you can skip the :logger configuration and add the handler directly to your application's Application.start/2 callback:

def start(_type, _args) do
  :logger.add_handler(:my_sentry_handler, Sentry.LoggerHandler, %{
    config: %{metadata: [:file, :line]}
  })

  # ...
end

configuration

 Configuration

This handler supports the following configuration options:

  • :excluded_domains (list of atom/0) - any messages with a domain in the configured list will not be sent. Defaults to [:cowboy] to avoid double-reporting events from Sentry.PlugCapture.

  • :metadata (list of atom/0, or :all) - use this to include non-Sentry logger metadata in reports. If it's a list of keys, metadata in those keys will be added in the :extra context (see Sentry.Context.set_extra_context/1) under the :logger_metadata key. If set to :all, all metadata will be included. Defaults to [].

  • :level (Logger.level/0) - the minimum Logger level to send events for. Defaults to :error.

  • :capture_log_messages (boolean/0) - when true, this module will report all logged messages to Sentry (provided they're not filtered by :excluded_domains and :level). Defaults to false, which will only send crash reports, which are messages with metadata that has the shape of an exit reason and a stacktrace.