Sentry
Sentry
v10.2.0

View Source Sentry.Event (Sentry v10.2.0)

Provides functions to create Sentry events from scratch, from exceptions, and so on.

This module also contains the main event struct. Events are the fundamental data that clients send to the Sentry server.

See https://develop.sentry.dev/sdk/event-payloads.

Link to this section Summary

Types

level()

The level of an event.

t()

The type for the event struct.

Functions

%Sentry.Event{}

The struct representing the event.

create_event(opts)

Creates an event struct out of collected context and options.

transform_exception(exception, opts)

Transforms an exception to a Sentry event.

Link to this section Types

Link to this type

level()

View Source (since 9.0.0) 
@type level() :: :fatal | :error | :warning | :info | :debug

The level of an event.

Link to this type

t()

View Source 
@type t() :: %Sentry.Event{
  attachments: [Sentry.Attachment.t()],
  breadcrumbs: [Sentry.Interfaces.Breadcrumb.t()],
  contexts: Sentry.Interfaces.context(),
  culprit: term(),
  dist: String.t() | nil,
  environment: String.t() | nil,
  event_id: <<_::256>>,
  exception: [Sentry.Interfaces.Exception.t()],
  extra: map(),
  fingerprint: [String.t()],
  level: level() | nil,
  logger: String.t() | nil,
  message: Sentry.Interfaces.Message.t() | nil,
  modules: %{optional(String.t()) => String.t()},
  original_exception: Exception.t() | nil,
  platform: :elixir,
  release: String.t() | nil,
  request: Sentry.Interfaces.Request.t() | nil,
  sdk: Sentry.Interfaces.SDK.t() | nil,
  server_name: String.t() | nil,
  source: atom(),
  tags: %{optional(String.t()) => String.t()},
  threads: [Sentry.Interfaces.Thread.t()] | nil,
  timestamp: String.t() | number(),
  transaction: String.t() | nil,
  user: Sentry.Interfaces.user() | nil
}

The type for the event struct.

All of the fields in this struct map directly to the fields described in the Sentry documentation. These fields are the exceptions, and are specific to the Elixir Sentry SDK:

  • :source - the source of the event. Sentry.LoggerBackend and Sentry.LoggerHandler set this to :logger, while Sentry.PlugCapture and Sentry.PlugContext set it to :plug. You can set it to any atom. See the :event_source option in create_event/1 and transform_exception/2.

  • :original_exception - the original exception that is being reported, if there's one. The Elixir Sentry SDK manipulates reported exceptions to make them fit the payload required by the Sentry API, and these end up in the :exception field. The :original_exception field, instead, contains the original exception as the raw Elixir term (such as %RuntimeError{...}).

See also %Sentry.Event{}.

Link to this section Functions

Link to this function

%Sentry.Event{}

View Source (struct)

The struct representing the event.

You're not advised to manipulate this struct's fields directly. Instead, use functions such as create_event/1 or transform_exception/2 for creating events.

See the t/0 type for information on the fields and their types.

Link to this function

create_event(opts)

View Source 
@spec create_event([option]) :: t()
when option:
       {:exception, term()}
       | {:stacktrace,
          [{atom(), atom(), term(), keyword()} | {term(), term(), keyword()}]}
       | {:message, binary()}
       | {:extra, %{optional(atom() | binary()) => term()}}
       | {:user, map()}
       | {:tags, %{optional(atom() | binary()) => term()}}
       | {:request, map()}
       | {:breadcrumbs, [keyword() | map()]}
       | {:level, term()}
       | {:fingerprint, [binary()]}
       | {:event_source, atom()}
       | {:interpolation_parameters, [term()]}
       | {:handled, boolean()}

Creates an event struct out of collected context and options.

Merging Options with Context and Config

Some of the options documented below are merged with the Sentry context, or with the Sentry context and the configuration. The option you pass here always has higher precedence, followed by the context and finally by the configuration.

See also Sentry.Context for information on the Sentry context and Sentry for information on configuration.

options

 Options

  • :exception (Exception.t/0) - This is the exception that gets reported in the :exception field of t/0. The term passed here also ends up unchanged in the :original_exception field of t/0. This option is required unless the :message option is present. Not present by default.

  • :stacktrace (Exception.stacktrace/0) - The exception's stacktrace. This can also be used with messages (:message). Not present by default.

  • :message (String.t/0) - A message to report. The string can contain interpolation markers (%s). In that case, you can pass the :interpolation_parameters option as well to fill in those parameters. See Sentry.capture_message/2 for more information on message interpolation. Not present by default.

  • :extra (Sentry.Context.extra/0) - Map of extra context, which gets merged with the current context (see Sentry.Context.set_extra_context/1). If fields collide, the ones in the map passed through this option have precedence over the ones in the context. The default value is %{}.

  • :user (Sentry.Context.user_context/0) - Map of user context, which gets merged with the current context (see Sentry.Context.set_user_context/1). If fields collide, the ones in the map passed through this option have precedence over the ones in the context. The default value is %{}.

  • :tags (Sentry.Context.tags/0) - Map of tags context, which gets merged with the current context (see Sentry.Context.set_tags_context/1) and with the :tags option in the global Sentry configuration. If fields collide, the ones in the map passed through this option have precedence over the ones in the context, which have precedence over the ones in the configuration. The default value is %{}.

  • :request (Sentry.Context.request_context/0) - Map of request context, which gets merged with the current context (see Sentry.Context.set_request_context/1). If fields collide, the ones in the map passed through this option have precedence over the ones in the context. The default value is %{}.

  • :breadcrumbs (list of keyword/0 or Sentry.Context.breadcrumb/0) - List of breadcrumbs. This list gets prepended to the list in the context (see Sentry.Context.add_breadcrumb/1). The default value is [].

  • :level (level/0) - The level of the event. The default value is :error.

  • :fingerprint (list of String.t/0) - List of the fingerprint for grouping this event. The default value is ["{{ default }}"].

  • :event_source (atom/0) - The source of the event. This fills in the :source field of the returned struct. This is not present by default.

  • :interpolation_parameters (list of term/0) - The parameters to use for message interpolation. This is only used if the :message option is present. This is not present by default. See Sentry.capture_message/2. Available since v10.1.0.

examples

 Examples 

iex> event = create_event(exception: %RuntimeError{message: "oops"}, level: :warning)
iex> event.level
:warning
iex> hd(event.exception).type
"RuntimeError"
iex> event.original_exception
%RuntimeError{message: "oops"}

iex> event = create_event(message: "Unknown route", event_source: :plug)
iex> event.source
:plug
Link to this function

transform_exception(exception, opts)

View Source 
@spec transform_exception(
  Exception.t(),
  keyword()
) :: t()

Transforms an exception to a Sentry event.

This essentially defers to create_event/1, inferring some options from the given exception.

options

 Options

This function takes the same options as create_event/1.