View Source Sentry.Event (Sentry v10.8.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.

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.

Types

level()

(since 9.0.0)

@type level() :: :fatal | :error | :warning | :info | :debug

The level of an event.

t()

@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()],
  integration_meta: map(),
  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{...}).
:integration_meta - a free-form map of integration-specific metadata. Integrations (such as the Oban integration) can set this field to store metadata that is specific to the integration. This field is not part of the Sentry API payload, but you can use it for example in :before_send callbacks to determine whether to report events. Available since v10.7.0.

Functions

%Sentry.Event{}

(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.

create_event(opts)

@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()]}
       | {:integration_meta, map()}
       | {: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

:exception (Exception.t/0) - This is the exception that gets reported in the :exception field of Sentry.Event.t/0. The term passed here also ends up unchanged in the :original_exception field of Sentry.Event.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

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

transform_exception(exception, opts)

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

Transforms an exception to a Sentry event.

This essentially defers to create_event/1.

Options

This function takes the same options as create_event/1, except for the :exception option.