View Source telemetry (telemetry v1.0.0)
telemetry
allows you to invoke certain functions whenever a particular event is emitted.
attach/4
, attach_many/4
and execute/2
.
Link to this section Summary
Functions
Attaches the handler to the event.
Attaches the handler to many events.
Removes the existing handler.
Emits the event, invoking handlers attached to it.
Returns all handlers attached to events with given prefix.
Runs the provided SpanFunction
, emitting start and stop/exception events, invoking the handlers attached to each.
Link to this section Types
Specs
event_measurements() :: map().
Specs
event_metadata() :: map().
Specs
event_name() :: [atom(), ...].
Specs
event_prefix() :: [atom()].
Specs
event_value() :: number().
Specs
handler() :: #{id := handler_id(), event_name := event_name(), function := handler_function(), config := handler_config()}.
Specs
handler_config() :: term().
Specs
handler_function() :: fun((event_name(), event_measurements(), event_metadata(), handler_config()) -> any()).
Specs
handler_id() :: term().
Specs
span_function() :: fun(() -> {span_result(), event_metadata()}).
Specs
span_result() :: term().
Link to this section Functions
Specs
attach(HandlerId, EventName, Function, Config) -> ok | {error, already_exists} when HandlerId :: handler_id(), EventName :: event_name(), Function :: handler_function(), Config :: handler_config().
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.
All the handlers are executed by the process dispatching event. If the function fails (raises, exits or throws) then the handler is removed and a failure event is emitted.
Handler failure events [telemetry, handler, failure]
should only be used for monitoring and diagnostic purposes. Re-attaching a failed handler will likely result in the handler failing again.
Specs
attach_many(HandlerId, [EventName], Function, Config) -> ok | {error, already_exists} when HandlerId :: handler_id(), EventName :: event_name(), Function :: handler_function(), Config :: handler_config().
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 invocations 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.
All the handlers are executed by the process dispatching event. If the function fails (raises, exits or throws) a handler failure event is emitted and then the handler is removed.
Handler failure events [telemetry, handler, failure]
should only be used for monitoring and diagnostic purposes. Re-attaching a failed handler will likely result in the handler failing again.
Specs
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.
Specs
execute(EventName, Measurements) -> ok when EventName :: event_name(), Measurements :: event_measurements() | event_value().
Equivalent to execute(EventName, Measurements, #{}).
Specs
execute(EventName, Measurements, Metadata) -> ok when EventName :: event_name(), Measurements :: event_measurements() | event_value(), Metadata :: event_metadata().
Emits the event, invoking handlers attached to it.
When the event is emitted, the handler function provided toattach/4
is called with four arguments:- the event name
- the map of measurements
- the map of event metadata
- the handler configuration given to
attach/4
Best practices and conventions:
While you are able to emit messages of any event_name
structure, it is recommended that you follow the the guidelines laid out in span/3
if you are capturing start/stop events.
Specs
list_handlers(event_prefix()) -> [handler()].
Returns all handlers attached to events with given prefix.
Handlers attached to many events at once usingattach_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.
Specs
span(event_prefix(), event_metadata(), span_function()) -> span_result().
Runs the provided SpanFunction
, emitting start and stop/exception events, invoking the handlers attached to each.
The SpanFunction
must return a {result, stop_metadata}
tuple.
execute/3
. Those events will be one of the following pairs:EventPrefix ++ [start]
andEventPrefix ++ [stop]
EventPrefix ++ [start]
andEventPrefix ++ [exception]
However, note that in case the current process crashes due to an exit signal of another process, then none or only part of those events would be emitted. Below is a breakdown of the measurements and metadata associated with each individual event.
When providing StartMetadata
and StopMetadata
, these values will be sent independently to start
and stop
events. If an exception occurs, exception metadata will be merged onto the StartMetadata
. In general, StopMetadata
should only provide values that are additive to StartMetadata
so that handlers, such as those used for metrics, can rely entirely on the stop
event.
A default span context is added to event metadata under the telemetry_span_context
key if none is provided by the user in the StartMetadata
. This context is useful for tracing libraries to identify unique executions of span events within a process to match start, stop, and exception events. Users should ensure this value is unique within the context of a process at a minimum if overriding this key and that the same value is provided to both StartMetadata
and StopMetadata
.
For telemetry
events denoting the start of a larger event, the following data is provided:
- Event:
EventPrefix ++ [start]
- Measurements:
#{ % The current system time in native units from % calling: erlang:system_time() system_time => integer(), monotonic_time => integer(), }
- Metadata:
#{ telemetry_span_context => term(), % User defined metadata as provided in StartMetadata ... }
telemetry
events denoting the stop of a larger event, the following data is provided:- Event:
EventPrefix ++ [stop]
- Measurements:
#{ % The current monotonic time minus the start monotonic time in native units % by calling: erlang:monotonic_time() - start_monotonic_time duration => integer(), monotonic_time => integer() }
- Metadata:
#{ % An optional error field if the stop event is the result of an error % but not necessarily an exception. error => term(), telemetry_span_context => term(), % User defined metadata as provided in StopMetadata ... }
telemetry
events denoting an exception of a larger event, the following data is provided:- Event:
EventPrefix ++ [exception]
- Measurements:
#{ % The current monotonic time minus the start monotonic time in native units % derived by calling: erlang:monotonic_time() - start_monotonic_time duration => integer(), monotonic_time => integer() }
- Metadata:
#{ kind => throw | error | exit, reason => term(), stacktrace => list(), telemetry_span_context => term(), % User defined metadata as provided in StartMetadata ... }