View Source Sibyl.Events (Sibyl v0.1.4)

Module containing the core business logic of Sibyl.

Includes utility functions to defining events, emitting events, and reflecting on events which are defined in any module loaded on the BEAM.

Link to this section Summary

Functions

Given an atom denoting some abstract event (but not of type event()), builds an event name such that the given abstract event is formatted as per telemetry best practices.

Builds a consistent telemetry event name following the conventions specified in this post.

Defines the given event.

Returns true if event was defined.

Given a module that may, or may not, use Sibyl as well as an event, returns true if said module defines the given event.

Returns a list of all telemetry events which have been defined by Sibyl.Events

Returns a list of all telemetry events which have been defined by Sibyl.Events for the given module.

Link to this section Types

@type ast() :: term()
@type event() :: [atom()]

Link to this section Functions

Link to this macro

build_event(event)

View Source (macro)
@spec build_event(event_fragment :: atom()) :: ast()

Given an atom denoting some abstract event (but not of type event()), builds an event name such that the given abstract event is formatted as per telemetry best practices.

examples-assuming-this-is-being-called-in-a-module-and-function

Examples (assuming this is being called in a module and function)

iex> Sibyl.Events.build_event(:not_found)
[:my_app, :"some_function/2", :not_found]
Link to this function

build_event(module, function, arity, event \\ nil)

View Source
@spec build_event(module(), function :: atom(), arity :: integer(), event :: atom()) ::
  event()
@spec build_event(module(), function :: nil, arity :: nil, event :: atom()) :: event()

Builds a consistent telemetry event name following the conventions specified in this post.

Called like: Sibyl.build_event(MyApp.Accounts, :register_user, 2, :email_sent), produces the following event: [:my_app, :accounts, :"register_user/2", :email_sent]

Link to this macro

define_event(event, module \\ nil)

View Source (macro)
@spec define_event(event(), module() | nil) :: ast()

Defines the given event.

Events should only be used once they are defined. Unless this is done, reflect/0 and reflect/1 will fail to see said event and will eventually throw errors.

When given a singular atom, it is assumed that the event you are trying to define is namespaced to said module as: [:my_app, :my_module, :custom_event].

When given a list of atoms, the event is simply registered as whatever you passed in; i.e. [:some, :custom, :event].

Link to this function

emit(event, measurements \\ %{}, metadata \\ %{})

View Source
@spec emit(event(), measurements :: map(), metadata :: map()) :: :ok

See emit/4

Link to this function

emit(module, event, measurements, metadata)

View Source
@spec emit(module(), event(), measurements :: map(), metadata :: map()) :: :ok
@spec emit(module(), atom(), measurements :: map(), metadata :: map()) :: :ok

Emits the given event.

Note: this is a low level API which should not be called outside of Sibyl's own code, and largely exists to plumb together the system.

Please prefer to use Sibyl.emit/3 which includes compile time checks to make sure the events being emitted were registered.

When given an event as an atom, tries to emit the event namespaced to the given module (see define_event/2 for more information).

When given a event as a list, simply emits that given list.

@spec is_event(event()) :: boolean()

Returns true if event was defined.

@spec is_event(module(), event()) :: boolean()

Given a module that may, or may not, use Sibyl as well as an event, returns true if said module defines the given event.

@spec reflect() :: [event()]

Returns a list of all telemetry events which have been defined by Sibyl.Events

@spec reflect(module()) :: [event()]

Returns a list of all telemetry events which have been defined by Sibyl.Events for the given module.

Note: some events may be implicitly defined via the top level @decorate trace() or @decorate_all trace() decorators.