Module telemetry

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

Description

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

For more information see the documentation for attach/4, attach_many/4 and execute/2.

Data Types

event_measurements()

event_measurements() = map()

event_metadata()

event_metadata() = map()

event_name()

event_name() = [atom(), ...]

event_prefix()

event_prefix() = [atom()]

event_value()

event_value() = number()

handler()

handler() = #{id => handler_id(), event_name => event_name(), function => handler_function(), config => handler_config()}

handler_config()

handler_config() = term()

handler_function()

handler_function() = fun((event_name(), event_measurements(), event_metadata(), handler_config()) -> any())

handler_id()

handler_id() = term()

Function Index

attach/4Attaches the handler to the event.
attach_many/4Attaches the handler to many events.
detach/1Removes the existing handler.
execute/2Equivalent to telemetry:execute(EventName, Measurements, #{}).
execute/3Emits the event, invoking handlers attached to it.
list_handlers/1Returns all handlers attached to events with given prefix.

Function Details

attach/4

attach(HandlerId, EventName, Function, Config) -> 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.

Note: due to how anonymous functions are implemented in the Erlang VM, it is best to use function captures (i.e. fun mod:fun/4 in Erlang or &Mod.fun/4 in Elixir) as event handlers to achieve maximum performance. In other words, avoid using literal anonymous functions (fun(...) -> ... end or fn ... -> ... end) or local function captures (fun handle_event/4 or &handle_event/4 ) as event handlers.

attach_many/4

attach_many(HandlerId, EventNames::[EventName], Function, Config) -> 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).

Note: due to how anonymous functions are implemented in the Erlang VM, it is best to use function captures (i.e. fun mod:fun/4 in Erlang or &Mod.fun/4 in Elixir) as event handlers to achieve maximum performance. In other words, avoid using literal anonymous functions (fun(...) -> ... end or fn ... -> ... end) or local function captures (fun handle_event/4 or &handle_event/4 ) as event handlers.

detach/1

detach(HandlerId::handler_id()) -> ok | {error, not_found}

Removes the existing handler.

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

execute/2

execute(EventName, Measurements) -> ok

Equivalent to telemetry:execute(EventName, Measurements, #{}).

execute/3

execute(EventName, Measurements, Metadata) -> ok

Emits the event, invoking handlers attached to it.

When the event is emitted, the handler function provided to attach/4 is called with four arguments: 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.

list_handlers/1

list_handlers(EventPrefix::event_prefix()) -> [handler()]

Returns all handlers attached to events with given prefix.

Handlers attached to many events at once using attach_many/4 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.


Generated by EDoc