Provides the functionality to submit events to Sentry.

This library can be used to submit events to Sentry from any Elixir application. It supports several ways of reporting events:

• Manually — see capture_exception/2 and capture_message/2.

• Through an Erlang :logger handler — see Sentry.LoggerHandler.

• Through an Elixir Logger backend — see Sentry.LoggerBackend.

• Automatically for Plug/Phoenix applications — see the Setup with Plug and Phoenix guide, and the Sentry.PlugCapture and Sentry.PlugContext modules.

usage

Usage

Add the following to your production configuration:

# In config/prod.exs
config :sentry, dsn: "https://public:secret@app.getsentry.com/1",
  environment_name: :prod,
  tags: %{
    env: "production"
  }

Sentry uses the :dsn option to determine whether it should record exceptions. If :dsn is set, then Sentry records exceptions. If it's not set or set to nil, then simply no events are sent to Sentry.

Included Environments

Before v10.0.0, the recommended way to control whether to report events to Sentry was the :included_environments option (a list of environments to report events for). This was used together with the :environment_name option to determine whether to send events. :included_environments is deprecated in v10.0.0 in favor of setting or not setting :dsn. It will be removed in v11.0.0.

You can even rely on more specific logic to determine the environment name. It's not uncommon for most applications to have a "staging" environment. In order to handle this without adding an additional Mix environment, you can set an environment variable that determines the release level. By default, Sentry picks up the SENTRY_ENVIRONMENT variable (at runtime, when starging). Otherwise, you can read the variable at runtime. Do this only in config/runtime.exs so that it will work both for local development as well as Mix releases.

# In config/runtime.exs
if config_env() == :prod do
  config :sentry, dsn: "https://public:secret@app.getsentry.com/1",
    environment_name: System.fetch_env!("RELEASE_LEVEL")
end

In this example, we are getting the environment name from the RELEASE_LEVEL environment variable. Now, on our servers, we can set the environment variable appropriately. The config_env() == :prod check ensures that we only set :dsn in production, effectively only enabling reporting in production-like environments.

Sentry supports many configuration options. See the Configuration section for complete documentation.

configuration

Configuration

You can configure Sentry through the application environment. Configure the following keys under the :sentry application. For example, you can do this in config/config.exs:

# config/config.exs
config :sentry,
  # ...

Sentry reads the configuration when the :sentry application starts, and will not pick up any changes after that. This is in line with how other Sentry SDKs (and many other Erlang/Elixir libraries) work. The reason for this choice is performance: the SDK performs validation on application start and then caches the configuration (in :persistent_term).

Updating Configuration at Runtime

If you must update configuration at runtime, use put_config/2. This function is not efficient (since it updates terms in :persistent_term), but it works in a pinch. For example, it's useful if you're verifying that you send the right events to Sentry in your test suite, so you need to change the :dsn configuration to point to a local server that you can verify requests on.

Below you can find all the available configuration options.

Basic Options

• :dsn (String.t/0 or nil) - The DSN for your Sentry project. If this is not set, Sentry will not be enabled. If the SENTRY_DSN environment variable is set, it will be used as the default value. If :test_mode is true, the :dsn option is sometimes ignored; see Sentry.Test for more information. The default value is nil.

• :environment_name (String.t/0 or atom/0) - The current environment name. This is used to specify the environment that an event happened in. It can be any string shorter than 64 bytes, except the string "None". When Sentry receives an event with an environment, it creates that environment if it doesn't exist yet. If the SENTRY_ENVIRONMENT environment variable is set, it will be used as the value for this option. The default value is "production".

• :included_environments (list of atom/0 or String.t/0, or the atom :all) - Deprecated. The environments in which Sentry can report events. If this is a list, then :environment_name needs to be in this list for events to be reported. If this is :all, then Sentry will report events regardless of the value of :environment_name. This will be removed in v11.0.0.

• :release (String.t/0 or nil) - The release version of your application. This is used to correlate events with source code. If the SENTRY_RELEASE environment variable is set, it will be used as the default value. The default value is nil.

• :json_library (module/0) - A module that implements the "standard" Elixir JSON behaviour, that is, exports the encode/1 and decode/1 functions. If you use the default, make sure to add :jason as a dependency of your application. The default value is Jason.

• :server_name (String.t/0) - The name of the server running the application. Not used by default.

• :sample_rate (float/0) - The percentage of events to send to Sentry. A value of 0.0 will deny sending any events, and a value of 1.0 will send 100% of events. Sampling is applied after the :before_send callback. See where the Sentry documentation suggests this. Must be between 0.0 and 1.0 (included). The default value is 1.0.

• :tags (map of term/0 keys and term/0 values) - A map of tags to be sent with every event. The default value is %{}.

• :max_breadcrumbs (non_neg_integer/0) - The maximum number of breadcrumbs to keep. See Sentry.Context.add_breadcrumb/1. The default value is 100.

• :report_deps (boolean/0) - Whether to report application dependencies of your application alongside events. This list contains applications (alongside their version) that are loaded when the :sentry application starts. The default value is true.

• :log_level - The level to use when Sentry fails to send an event due to an API failure or other reasons. The default value is :warning.

• :in_app_module_allow_list (list of module/0) - A list of modules that is used to distinguish among stacktrace frames that belong to your app and ones that are part of libraries or core Elixir. This is used to better display the significant part of stacktraces. The logic is "greedy", so if your app's root module is MyApp and you configure this option to [MyApp], MyApp as well as any submodules (like MyApp.Submodule) would be considered part of your app. Defaults to []. The default value is [].

• :filter (module/0) - A module that implements the Sentry.EventFilter behaviour. Defaults to Sentry.DefaultEventFilter. See the Filtering Exceptions section below. The default value is Sentry.DefaultEventFilter.

• :dedup_events (boolean/0) - Whether to deduplicate events before reporting them to Sentry. If this option is true, then the SDK will store reported events for around 30 seconds after they're reported. Any time the SDK is about to report an event, it will check if it has already reported within the past 30 seconds. If it has, then it will not report the event again, and will log a message instead. Events are deduplicated by comparing their message, exception, stacktrace, and fingerprint. Available since v10.0.0. The default value is true.

• :test_mode (boolean/0) - Whether to enable test mode. When test mode is enabled, the SDK will check whether there is a process collecting events and avoid sending those events if that's the case. This is useful for testing—see Sentry.Test. :test_mode works in tandem with :dsn; this is described in detail in Sentry.Test. The default value is false.

• :integrations (keyword/0) - Configuration for integrations with third-party libraries. Every integration has its own option and corresponding configuration options. The default value is [].

  • :oban (keyword/0) - Configuration for the Oban integration. Available since v10.2.0.

    • :capture_errors (boolean/0) - Whether to capture errors from Oban jobs. When enabled, the Sentry SDK will capture errors that happen in Oban jobs, including when errors return {:error, reason} tuples. Available since 10.3.0. The default value is false.

    • :cron (keyword/0) - Configuration options for configuring crons for Oban.

      • :enabled (boolean/0) - Whether to enable the Oban integration. When enabled, the Sentry SDK will capture check-ins for Oban jobs. Available since v10.2.0. The default value is false.

  • :quantum (keyword/0) - Configuration for the Quantum integration. Available since v10.2.0.

    • :cron (keyword/0) - Configuration options for configuring crons for Quantum.
      • :enabled (boolean/0) - Whether to enable the Quantum integration. When enabled, the Sentry SDK will capture check-ins for Quantum jobs. Available since v10.2.0. The default value is false.

Hook Options

These options control hooks that this SDK can call before or after sending events.

• :before_send (before_send_event_callback/0) - Allows performing operations on the event before it is sent as well as filtering out the event altogether. If the callback returns nil or false, the event is not reported. If it returns an updated Sentry.Event, then the updated event is used instead. See the Event Callbacks section below for more information.

  :before_send is available since v10.0.0. Before, it was called :before_send_event.

• :before_send_event (before_send_event_callback/0) - Exactly the same as :before_send, but has been deprecated since v10.0.0.

• :after_send_event (after_send_event_callback/0) - Callback that is called after attempting to send an event. The result of the HTTP call as well as the event will be passed as arguments. The return value of the callback is not returned. See the Event Callbacks section below for more information.

Transport Options

These options control how this Sentry SDK sends events to the Sentry server.

• :send_result (send_type/0) - Controls what to return when reporting exceptions to Sentry. The default value is :none.

• :client (module/0) - A module that implements the Sentry.HTTPClient behaviour. Defaults to Sentry.HackneyClient, which uses hackney as the HTTP client. The default value is Sentry.HackneyClient.

• :send_max_attempts (pos_integer/0) - The maximum number of attempts to send an event to Sentry. The default value is 4.

• :hackney_opts (keyword/0) - Options to be passed to hackney. Only applied if :client is set to Sentry.HackneyClient. The default value is [pool: :sentry_pool].

• :hackney_pool_timeout (timeout/0) - The maximum time to wait for a connection to become available. Only applied if :client is set to Sentry.HackneyClient. The default value is 5000.

• :hackney_pool_max_connections (pos_integer/0) - The maximum number of connections to keep in the pool. Only applied if :client is set to Sentry.HackneyClient. The default value is 50.

Source Code Context Options

These options control how source code context is reported alongside events.

• :enable_source_code_context (boolean/0) - Whether to report source code context alongside events. The default value is false.

• :root_source_code_paths (list of Path.t/0) - Aa list of paths to the root of your application's source code. This is used to determine the relative path of files in stack traces. Usually, you'll want to set this to [File.cwd!()]. For umbrella apps, you should set this to all the application paths in your umbrella (such as [Path.join(File.cwd!(), "apps/app1"), ...]). Required if :enabled_source_code_context is true. The default value is [].

• :source_code_path_pattern (String.t/0) - A glob pattern used to determine which files to report source code context for. The glob "starts" from :root_source_code_paths. The default value is "**/*.ex".

• :source_code_exclude_patterns (list of Regex.t/0) - A list of regular expressions used to determine which files to exclude from source code context. The default value is [~r/\/_build\//, ~r/\/deps\//, ~r/\/priv\//, ~r/\/test\//].

• :source_code_map_path (Path.t/0) - The path to the source code map file. See mix sentry.package_source_code. Defaults to a private path inside Sentry's priv directory. Available since v10.2.0.

• :context_lines (pos_integer/0) - The number of lines of source code before and after the line that caused the exception to report. The default value is 3.

Configuration Through System Environment

Sentry supports loading some configuration from the system environment. The supported environment variables are: SENTRY_RELEASE, SENTRY_ENVIRONMENT, and SENTRY_DSN. See the :release, :environment_name, and :dsn configuration options respectively for more information.

filtering-exceptions

Filtering Exceptions

If you would like to prevent Sentry from sending certain exceptions, you can use the :before_send configuration option. See the Event Callbacks section below.

Before v9.0.0, the recommended way to filter out exceptions was to use a filter, that is, a module implementing the Sentry.EventFilter behaviour. This is still supported, but is not deprecated. See Sentry.EventFilter for more information.

event-callbacks

Event Callbacks

You can configure the :before_send and :after_send_event options to customize what happens before and/or after sending an event. The :before_send callback must be of type before_send_event_callback/0 and the :after_send_event callback must be of type after_send_event_callback/0. For example, you can set:

config :sentry,
  before_send: {MyModule, :before_send},
  after_send_event: {MyModule, :after_send}

MyModule could look like this:

defmodule MyModule do
  def before_send(event) do
    metadata = Map.new(Logger.metadata())
    %Sentry.Event{event | extra: Map.merge(event.extra, metadata)}
  end

  def after_send_event(event, result) do
    case result do
      {:ok, id} ->
        Logger.info("Successfully sent event!")

      {:error, _reason} ->
        Logger.info(fn -> "Did not successfully send event! #{inspect(event)}" end)
    end
  end
end

reporting-source-code

Reporting Source Code

Sentry supports reporting the source code of (and around) the line that caused an issue. An example configuration to enable this functionality is:

config :sentry,
  dsn: "https://public:secret@app.getsentry.com/1",
  enable_source_code_context: true,
  root_source_code_paths: [File.cwd!()],
  context_lines: 5

To support this functionality, Sentry needs to package source code and store it so that it's available in the compiled application. Packaging source code is an active step you have to take; use the mix sentry.package_source_code Mix task to do that.

Sentry stores the packaged source code in its priv directory. This is included by default in Mix releases. Once the source code is packaged and ready to ship with your release, Sentry will load it when the :sentry application starts. If there are issues with loading the packaged code, Sentry will log some warnings but will boot up normally and it just won't report source code context.

Prune Large File Trees

Due to Sentry reading the file system and defaulting to a recursive search of directories, it is important to check your configuration and compilation environment to avoid a folder recursion issue. You might see problems when deploying to the root folder, so it is best to follow the practice of compiling your application in its own folder. Modifying the :source_code_path_pattern configuration option from its default is also an avenue to avoid compile problems, as well as pruning unnecessary files with :source_code_exclude_patterns.