telemetry (telemetry v1.0.0) View Source

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.

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.

Emit 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

assert_event_name(term()) -> ok.
Link to this function

assert_event_names(List)

View Source

Specs

assert_event_names(term()) -> [ok].
Link to this function

assert_event_prefix(List)

View Source

Specs

assert_event_prefix(term()) -> ok.
Link to this function

attach(HandlerId, EventName, Function, Config)

View Source

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. Note that you should not rely on the order in which handlers are invoked.
Link to this function

attach_many(HandlerId, EventNames, Function, Config)

View Source

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) then the handler is removed. Note that you should not rely on the order in which handlers are invoked.

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.
Link to this function

execute(EventName, Measurements)

View Source

Specs

execute(EventName, Measurements) -> ok
           when EventName :: event_name(), Measurements :: event_measurements() | event_value().

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

Link to this function

execute(EventName, Measurements, Metadata)

View Source

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 to attach/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.

Link to this function

list_handlers(EventPrefix)

View Source

Specs

list_handlers(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.
Link to this function

merge_ctx(Metadata, Ctx)

View Source

Specs

merge_ctx(event_metadata(), any()) -> event_metadata().
Link to this function

span(EventPrefix, StartMetadata, SpanFunction)

View Source

Specs

Emit start, and stop/exception events, invoking the handlers attached to each.

When this function is called, 2 events will be emitted via execute/3. Those events will be one of the following pairs:
  • EventPrefix ++ [start] and EventPrefix ++ [stop]
  • EventPrefix ++ [start] and EventPrefix ++ [exception]

However, note that in case the current processes 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()
      }
  • Metadata:
      #{
        telemetry_span_context => term(),
        % User defined metadata
        ...
      }

For 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()
      }
  • Metadata:
      #{
        % An optional error field if the stop event is the result of an error
        % but not necessarily an exception. Additional user defined metadata can
        % also be added here.
        error => term(),
        telemetry_span_context => term(),
        ...
      }

For 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()
      }
  • Metadata:
      #{
        kind => throw | error | exit,
        reason => term(),
        stacktrace => list(),
        telemetry_span_context => term(),
        % User defined metadata from the start event
         ...
      }