defmodule Sentry do
@moduledoc ~S"""
Provides the functionality to submit events to [Sentry](https://sentry.io).
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 Elixir `Logger` backend — see `Sentry.LoggerBackend`.
* Automatically for Plug/Phoenix applications — see the
[*Setup with Plug and Phoenix* guide](setup-with-plug-and-phoenix.html), and the
`Sentry.PlugCapture` and `Sentry.PlugContext` modules.
## Usage
Add the following to your production configuration:
# In config/prod.exs
config :sentry, dsn: "https://public:secret@app.getsentry.com/1",
included_environments: [:prod],
environment_name: :prod,
tags: %{
env: "production"
}
The `:environment_name` and `:included_environments` options work together to determine
if and when Sentry should record exceptions. The `:environment_name` is the
name of the current environment. In the example above, we have explicitly set
the environment to `:prod` which works well if you are inside an environment
specific configuration `config/prod.exs`.
An alternative is to use `Config.config_env/0` in your general `config/config.exs`
configuration file:
config :sentry, dsn: "https://public:secret@app.getsentry.com/1",
included_environments: [:prod],
environment_name: config_env()
This will set the environment name to whatever the current environment
is, but it will only send events if the current environment is `:prod`,
since that is the only entry in the `:included_environments` key.
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. 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
config :sentry, dsn: "https://public:secret@app.getsentry.com/1",
included_environments: ["production", "staging"],
environment_name: System.get_env("RELEASE_LEVEL", "development")
In this example, we are getting the environment name from the `RELEASE_LEVEL`
environment variable. If that variable does not exist, we default to `"development"`.
Now, on our servers, we can set the environment variable appropriately. On
our local development machines, exceptions will never be sent, because the
default value is not in the list of `:included_environments`.
> #### Using the DSN To Send Events {: .warning}
>
> We recommend to use the `:dsn` configuration to control whether to report
> events. If `:dsn` is not set (or set to `nil`), then we won't report
> events to Sentry. Thanks to this behavior, you can essentially
> only set `:dsn` in environments where you want to report events to Sentry.
> In the future, we might remove the `:included_environments` configuration
> altogether.
Sentry supports many configuration options. See the [*Configuration*
section](#module-configuration) for complete documentation.
## 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,
# ...
The basic configuration options are:
* `:dsn` (`t:String.t/0`) - 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.
* `:release` (`t:String.t/0`) - 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.
* `:environment_name` (`t:atom/0` or `t:String.t/0`) - the current
environment name. This is used to determine if Sentry should be enabled
and if events should be sent. For events to be sent, the value of
this option must appear in the `:included_environments` list.
If the `SENTRY_ENVIRONMENT` environment variable is set, it will
be used as the defaults value. Otherwise, defaults to `"dev"`.
* `:included_environments` (list of `t:atom/0` or `t:String.t/0`, or the atom `:all`) -
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`. Defaults to `:all`.
* `:tags` (`t:map/0`) - a map of tags to be sent with every event.
Defaults to `%{}`.
* `:server_name` (`t:String.t/0`) - the name of the server running the
application. Not used by default.
* `:filter` (`t:module/0`) - a module that implements the `Sentry.Filter`
behaviour. Defaults to `Sentry.DefaultEventFilter`. See the
[*Filtering Exceptions* section](#module-filtering-exceptions) below.
* `:json_library` (`t:module/0`) - a module that implements the "standard"
Elixir JSON behaviour, that is, exports the `encode/1` and `decode/1`
functions. Defaults to `Jason`, which requires [`:jason`](https://hex.pm/packages/jason)
to be a dependency of your application.
* `:log_level` (`t:Logger.level/0`) - the level to use when Sentry fails to
send an event due to an API failure or other reasons. Defaults to `:warning`.
To customize what happens when sending an event, you can use these options:
* `:sample_rate` (`t:float/0` between `0.0` and `1.0`) - the percentage
of events to send to Sentry. Defaults to `1.0` (100% of events).
* `:send_result` (`t:atom/0`) - controls what to return when reporting exceptions
to Sentry. Defaults to `:none`.
* `:send_max_attempts` (`t:integer/0`) - the maximum number of attempts to
send an event to Sentry. Defaults to `4`.
* `:max_breadcrumbs` (`t:integer/0`) - the maximum number of breadcrumbs
to keep. Defaults to `100`. See `Sentry.Context.add_breadcrumb/1`.
* `:before_send_event` (`t: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](#module-event-callbacks) below for more information.
* `:after_send_event` (`t: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](#module-event-callbacks) below for more information.
* `:in_app_module_allow_list` (list of `t: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 `[]`.
To customize the behaviour of the HTTP client used by Sentry, you can
use these options:
* `:client` (`t:module/0`) - a module that implements the `Sentry.HTTPClient`
behaviour. Defaults to `Sentry.HackneyClient`, which uses
[hackney](https://github.com/benoitc/hackney) as the HTTP client.
* `:hackney_opts` (`t:keyword/0`) - options to be passed to `hackney`. Only
applied if `:client` is set to `Sentry.HackneyClient`. Defaults to
`[pool: :sentry_pool]`.
* `:hackney_pool_max_connections` (`t:integer/0`) - the maximum number of
connections to keep in the pool. Only applied if `:client` is set to
`Sentry.HackneyClient`. Defaults to `50`.
* `:hackney_pool_timeout` (`t:integer/0`) - the maximum time to wait for a
connection to become available. Only applied if `:client` is set to
`Sentry.HackneyClient`. Defaults to `5000`.
To customize options related to reporting source code context, you can use these
options:
* `:report_deps` (`t:boolean/0`) - whether to report Mix dependencies of your
application alongside events. If `true`, this attempts to load dependencies
*at compile time*. Defaults to `true`.
* `:enable_source_code_context` (`t:boolean/0`) - whether to report source
code context alongside events. Defaults to `false`.
* `:root_source_code_paths` (list of `t:Path.t/0`) - a 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`.
* `:source_code_path_pattern` (`t:String.t/0`) - a glob pattern used to
determine which files to report source code context for. The glon "starts"
from `:root_source_code_paths`. Defaults to `"**/*.ex"`.
* `:source_code_exclude_patterns` (list of `t:Regex.t/0`) - a list of regular
expressions used to determine which files to exclude from source code
context. Defaults to `[~r"/_build/", ~r"/deps/", ~r"/priv/"]`.
* `:context_lines` (`t:integer/0`) - the number of lines of source code
before and after the line that caused the exception to report. Defaults to `3`.
> #### Compile-time Configuration {: .tip}
>
> These options are only available at compile-time:
> * `:enable_source_code_context`
> * `:root_source_code_paths`
> * `:report_deps`
> * `:source_code_path_pattern`
> * `:source_code_exclude_patterns`
>
> If you change the value of any of these, you'll need to recompile Sentry itself.
> You can run `mix deps.compile sentry` to do that.
### Configuration Through System Environment
Sentry supports loading configuration from the system environment. You can do this
by setting `SENTRY_<name>` environment variables. For example, to set the `:release`
option through the system environment, you can set the `SENTRY_RELEASE` environment
variable.
The supported `SENTRY_<name>` environment variables are:
* `SENTRY_RELEASE`
* `SENTRY_ENVIRONMENT`
* `SENTRY_DSN`
## Filtering Exceptions
If you would like to prevent Sentry from sending certain exceptions, you can
use the `:before_send_event` configuration option. See the [*Event Callbacks*
section](#module-event-callbacks) 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
You can configure the `:before_send_event` and `:after_send_event` options to
customize what happens before and/or after sending an event. The `:before_send_event`
callback must be of type `t:before_send_event_callback/0` and the `:after_send_event`
callback must be of type `t:after_send_event_callback/0`. For example, you
can set:
config :sentry,
before_send_event: {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
Sentry supports reporting the source code of (and around) the line that
caused an issue. To support this functionality, this library stores
the text of source files during compilation. 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
File contents are saved when Sentry is compiled, which can cause some
complications. If a file is changed, and Sentry is not recompiled,
it will still report old source code.
The best way to ensure source code is up to date is to recompile Sentry
itself via `mix deps.compile sentry --force`. It's possible to create a Mix
task alias in `mix.exs` to do this. The example below would allow you to
run `mix sentry_recompile && mix compile` which will force recompilation of Sentry so
it has the newest source and then compile the project. The second `mix compile`
is required due to Mix only invoking the same task once in an alias.
defp aliases do
[sentry_recompile: ["compile", "deps.compile sentry --force"]]
end
This is an important to note especially when building for production. If your
build or deployment system caches prior builds, it may not recompile Sentry
and could cause issues with reported source code being out of date.
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. Problems may be seen 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.
"""
alias Sentry.{Config, Event}
require Logger
@typedoc """
A callback to use with the `:before_send_event` configuration option.
configuration options.k
If this is `{module, function_name}`, then `module.function_name(event)` will
be called, where `event` is of type `t:Sentry.Event.t/0`.
See the [*Configuration* section](#module-configuration) in the module documentation
for more information on configuration.
"""
@typedoc since: "9.0.0"
@type before_send_event_callback() ::
(Sentry.Event.t() -> as_boolean(Sentry.Event.t()))
| {module(), function_name :: atom()}
@typedoc """
A callback to use with the `:after_send_event` configuration option.
If this is `{module, function_name}`, then `module.function_name(event, result)` will
be called, where `event` is of type `t:Sentry.Event.t/0`.
"""
@typedoc since: "9.0.0"
@type after_send_event_callback() ::
(Sentry.Event.t(), result :: term() -> term())
| {module(), function_name :: atom()}
@typedoc """
The strategy to use when sending an event to Sentry.
"""
@typedoc since: "9.0.0"
@type send_type() :: :sync | :none
@type send_result() ::
{:ok, event_or_envelope_id :: String.t()}
| {:error, term()}
| :ignored
| :unsampled
| :excluded
@doc """
Parses and submits an exception to Sentry
This only sends the exception if the current Sentry environment is in
the `:included_environments`. See the [*Configuration* section](#module-configuration)
in the module documentation.
The `opts` argument is passed as the second argument to `send_event/2`.
"""
@spec capture_exception(Exception.t(), keyword()) :: send_result
def capture_exception(exception, opts \\ []) do
filter_module = Config.filter()
event_source = Keyword.get(opts, :event_source)
if filter_module.exclude_exception?(exception, event_source) do
:excluded
else
exception
|> Event.transform_exception(opts)
|> send_event(opts)
end
end
@doc """
Puts the last event ID sent to the server for the current process in
the process dictionary.
"""
@spec put_last_event_id_and_source(String.t()) :: {String.t(), atom() | nil} | nil
def put_last_event_id_and_source(event_id, source \\ nil) when is_binary(event_id) do
Process.put(:sentry_last_event_id_and_source, {event_id, source})
end
@doc """
Gets the last event ID sent to the server from the process dictionary.
Since it uses the process dictionary, it will only return the last event
ID sent within the current process.
"""
@spec get_last_event_id_and_source() :: {String.t(), atom() | nil} | nil
def get_last_event_id_and_source do
Process.get(:sentry_last_event_id_and_source)
end
@doc """
Reports a message to Sentry.
`opts` argument is passed as the second argument to `Sentry.send_event/2`.
"""
@spec capture_message(String.t(), keyword()) :: send_result
def capture_message(message, opts \\ []) when is_binary(message) do
opts
|> Keyword.put(:message, message)
|> Event.create_event()
|> send_event(opts)
end
@doc """
Sends an event to Sentry.
An **event** is the most generic payload you can send to Sentry. It encapsulates
information about an exception, a message, or any other event that you want to
report. To manually build events, see the functions in `Sentry.Event`.
## Options
The supported options are:
* `:result` - Allows specifying how the result should be returned. The possible values are:
* `:sync` - Sentry will make an API call synchronously (including retries) and will
return `{:ok, event_id}` if successful.
* `:none` - Sentry will send the event in the background, in a *fire-and-forget*
fashion. The function will return `{:ok, ""}` regardless of whether the API
call ends up being successful or not.
* `:async` - **Not supported anymore**, see the information below.
* `:sample_rate` - The sampling factor to apply to events. 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_event` callback. See where [the Sentry
documentation](https://develop.sentry.dev/sdk/sessions/#filter-order) suggests this.
* Other options, such as `:stacktrace` or `:extra`, will be passed to
`Sentry.Event.create_event/1` downstream. See `Sentry.Event.create_event/1`
for available options.
> #### Async Send {: .error}
>
> Before v9.0.0 of this library, the `:result` option also supported the `:async` value.
> This would spawn a `Task` to make the API call, and would return a `{:ok, Task.t()}` tuple.
> You could use `Task` operations to wait for the result asynchronously. Since v9.0.0, this
> option is not present anymore. Instead, you can spawn a task yourself that then calls this
> function with `result: :sync`. The effect is exactly the same.
> #### Sending Exceptions and Messages {: .tip}
>
> This function is **low-level**, and mostly intended for library developers,
> or folks that want to have full control on what they report to Sentry. For most
> use cases, use `capture_exception/2` or `capture_message/2`.
"""
@spec send_event(Event.t(), keyword()) :: send_result
def send_event(event, opts \\ [])
def send_event(%Event{message: nil, exception: []}, _opts) do
Logger.log(Config.log_level(), "Sentry: unable to parse exception")
:ignored
end
def send_event(%Event{} = event, opts) do
included_environments = Config.included_environments()
environment_name = to_string(Config.environment_name())
if included_environments == :all or environment_name in included_environments do
Sentry.Client.send_event(event, opts)
else
:ignored
end
end
end
