Telemetry

v0.2.0

Telemetry v0.2.0 Telemetry View Source

Telemetry allows you to invoke certain functions whenever a particular event is emitted.

For more information see the documentation for attach/5, attach_many/5 and execute/3.

Link to this section Summary

Types

event_metadata()
event_name()
event_prefix()
event_value()
handler_id()

Functions

attach(handler_id, event_name, module, function, config)

Attaches the handler to the event

attach_many(handler_id, event_names, module, function, config)

Attaches the handler to many events

detach(handler_id)

Removes the existing handler

execute(event_name, value, metadata \\ %{})

Emits the event, invoking handlers attached to it

list_handlers(event_prefix)

Returns all handlers attached to events with given prefix

Link to this section Types

Link to this type event_metadata() View Source 
event_metadata() :: map()
Link to this type event_name() View Source 
event_name() :: [atom()]
Link to this type event_prefix() View Source 
event_prefix() :: [atom()]
Link to this type event_value() View Source 
event_value() :: number()
Link to this type handler_id() View Source 
handler_id() :: term()

Link to this section Functions

Link to this function attach(handler_id, event_name, module, function, config) View Source 
attach(
  handler_id(),
  event_name(),
  module(),
  function :: atom(),
  config :: term()
) :: :ok | {:error, :already_exists}

Attaches the handler to the event.

handler_id must be unique, if another handler with the same ID already exists the {:error, :already_exists} tuple is returned.

See execute/3 to learn how the handlers are invoked.

Link to this function attach_many(handler_id, event_names, module, function, config) View Source 
attach_many(
  handler_id(),
  [event_name()],
  module(),
  function :: atom(),
  config :: term()
) :: :ok | {:error, :already_exists}

Attaches the handler to many events.

The handler will be invoked whenever any of the events in the event_names list is emitted. Note that failure of the handler on any of these invokations will detach it from all the events in event_name (the same applies to manual detaching using detach/1).

Link to this function detach(handler_id) View Source 
detach(handler_id()) :: :ok | {:error, :not_found}

Removes the existing handler.

If the handler with given ID doesn’t exist, {:error, :not_found} is returned.

Link to this function execute(event_name, value, metadata \\ %{}) View Source 
execute(event_name(), event_value(), event_metadata()) :: :ok

Emits the event, invoking handlers attached to it.

When the event is emitted, module.function provided to attach/5 is called with four arguments:

  • the event name
  • the event value
  • the event metadata
  • the handler configuration given to attach/5

All the handlers are executed by the process calling this function. If the function fails (raises, exits or throws) then the handler is removed.

Note that you should not rely on the order in which handlers are invoked.

Link to this function list_handlers(event_prefix) View Source 
list_handlers(event_prefix()) :: [
  {handler_id(), event_name(), module(), function :: atom(), config :: term()}
]

Returns all handlers attached to events with given prefix.

Handlers attached to many events at once using attach_many/5 will be listed once for each event they’re attached to.

Note that you can list all handlers by feeding this function an empty list.