TelemetryRegistry provides tools for the discovery and documentation of telemetry events within your applications.

telemetry-event-definitions-and-declaration

Telemetry Event Definitions and Declaration

Users want to know what telemetry events are available in your library, what they mean, as well as what the measurements and metadata maps contain. TelemetryRegistry creates an official standard and mechanism for telemetry event declaration and definition.

who-should-document-events

Who Should Document Events?

Library authors in particular should provide event declarations for documentation and to simplify tracing. Of course, everyone should document their modules!

where-should-i-declare-events

Where Should I Declare Events?

Events should only be declared once, usually in the module from which it originates. Event names should always be namespaced to your application or library. For example, if your application is an http client, your events should start with the name of your application, not a generic name.

Do: [:tesla, :request, :stop]

Don't: [:http_client, :request, :stop]

event-definition-format

Event Definition Format

Events are declared using the telemetry_event module attribute. The attribute accepts an event definition which are used for producing documentation and event discovery. All definition keys are required.

%{
  event: [:my_app, :event, :stop],
  description: "A description of what the event is and when it is emitted",
  measurements: "A string containing a pseudo or typespec - see examples",
  metadata: "A string containing a pseudo or real typespec - see examples"
}

#{
  event => [my_app, event, stop],
  description => <<"A description of what the event is and when it is emitted">>,
  measurements => <<"A string containing a pseudo or typespec - see examples">>,
  metadata => <<"A string containing a pseudo or real typespec - see examples">>
}

Elixir

Elixir does not allow for declaring a custom attribute multiple times by default. We have included macros to help with this and to provide a way to include event documentation.

defmodule TestElixirApp do
  use TelemetryRegistry

  telemetry_event %{
    event: [:test_elixir_app, :single, :event],
    description: "emitted when this event happens",
    measurements: "%{duration: non_neg_integer()}",
    metadata: "%{status: status(), name: String.t()}"
  }

  @moduledoc """
  Module documentation...

  ## Telemetry

  #{telemetry_docs()}

  """
end

Add use TelemetryRegistry at the top of your module to prep your module for defining events. This handles setting up everything needed to declare events and the very helpful telemetry_event/1 macro.

event-discovery

Event Discovery

Events can be discovered by invoking discover_all, usually during application startup. The registry will walk through the application tree and aggregate all events. The events are cached, so this should only be invoked once at startup. You can view all declared events using list_events/0. It is also possible to limit event discovery to a particular application tree by passing an application name to discover_all/1.

distributed-tracing

Distributed Tracing

Event discovery is critical for supporting distributed tracing of black-box libraries used in your application. Library authors are encouraged to use telemetry events in their libraries to provide insight of internal operations to users in a vendor-agnostic manner.

TelemetryRegistry provides a mechanism through spannable_events/0 for distributed tracing library authors to discover events which can be used to start and stop child spans by registering telemetry event handlers automatically at runtime with no user intervention. Library authors can then provide additional mechanisms for users to enhance spans with attributes created from telemetry event measurements and metadata.