View Source Overview

EEF Observability WG project Hex.pm

Telemetry Registry

TelemetryRegistry is a library for Telemetry event declaration, discovery, and registration. Events are declared using the module attribute telemetry_event and include a description of the event, measurements, and metadata.

how-it-works

How It Works

The Registry works by walking an application tree and examining every module for Telemetry Event definitions when invoking the discovery feature.

-telemetry_event #{
                   event => [test_app, handler, start],
                   description => <<"Emitted at the start of the handler">>,
                   measurements => <<"#{system_time => non_neg_integer()}">>,
                   metadata => <<"#{}">>
                  }.
-telemetry_event #{
                   event => [test_app, handler, stop],
                   description => <<"Emitted at the end of the handler">>,
                   measurements => <<"#{duration => non_neg_integer()}">>,
                   metadata => <<"#{}">>
                  }.
-telemetry_event #{
                   event => [test_app, handler, exception],
                   description => <<"The handler raised an exception">>,
                   measurements => <<"#{duration => non_neg_integer()}">>,
                   metadata => <<"#{kind => atom(), reason => atom(), stacktrace => term()}">>
                  }.

add-the-registry-to-your-application

Add the Registry to Your Application

After the applications are loaded, simply run

telemetry_registry:discover_all(my_app).

Or if you want to load all applications loaded in current VM then you can use:

telemetry_registry:discover_all().

viewing-events

Viewing Events

The defined events can be accessed using list_events/0. Events are returned as a list of three element tuples of {Event, Module, Meta} where Event is the event name, Module is the module it was discovered in, and Meta is the event definition metadata.

telemetry_registry:list_events().

spannable-events

Spannable Events

Tracing spans need at least a matching start and stop event to create a child span. Optionally, a exception event can be emitted in the case of an exception being raised. spannable_events/0 returns a proplist of all matching (spannable) events that have been discovered. These are returned as a proplist with keys being the event prefix and the value being a list of the available events, e.g. [{[test_app,handler], [start,stop,exception]}].

telemetry_registry:spannable_events().
%% [{[test_app,handler], [start,stop,exception]}]

elixir-users

Elixir Users

A variety of macros to assist with event declaration and generating telemetry event documentation are available. Please refer to the HexDocs for more information.

dependency-in-elixir

Dependency in Elixir

def deps do
  [
    {:telemetry_registry, "~> 0.3"}
  ]
end

Copyright 2020 Bryan Naegele

TelemetryRegistry source code is released under Apache License, Version 2.0.