beam-telemetry / telemetry_registry Goto Github PK

Background

Users currently rely on discovery and documentation of telemetry events in two manners: reading source code and documentation. To make use of events users must have an understanding of the following:

• event name
• available measurements
• available metadata

The general pattern in use today which we've iterated towards in Elixir is:

• [:my_event, :name] - general description of what the event is
  • Measurement: %{map_of: pseudo_type_spec}
  • Metadata: %{map_of: pseudo_type_spec}

This has worked fairly well for most users I've interacted with, so we should build on this as a starting point to support documentation and discovery.

Proposal

Telemetry module event attributes should support an event definition map, in addition to a plain event, such as [my_app, event, stop] to provide a standard for documentation which can be leveraged by tools like ex_doc

Example

-telemetry_event([my_app, some, event]).
-telemetry_event(#{
    event => [my_app, event, stop],
    description => "A description of the event",
    measurement => "`#{duration => non_neg_integer()}`",
    metadata => "`#{status => 200 | 400 | 404, method => string()}`"
}).

Plain events would be stored with empty string defaults for the other properties of a definition.

Discussion

While it would be nifty to use actual typespecs for the measurement and metadata, I'm unfamiliar with any way to accomplish that, especially cross-language. If there isn't a way to leverage typespecs, a plain string with the user using a single-line code block of pseduo-typespec feels sufficient. The primary use case for the measurement and metadata information is to inform users of what is available.

Status: Accepted

Add support for enhanced definitions similar to https://github.com/keathley/finch/blob/master/lib/finch/telemetry.ex by accepting a proplist of [{atom | binary, binary}] in place of a string and formatting accordingly. This should be fairly straightforward to implement.

I think this is the commit corresponding to the published version of the package in hex.pm, but it's not tagged in github. https://github.com/beam-telemetry/telemetry_registry/tree/b2ce52176a3f5b100750f1152bff3b5c57de1f44

I'd love to make TelemetryDecorator event names easier to discover (amplifiedai/telemetry_decorator#2). Assuming I can figure out a way to emit module-level AST chunks (arjan/decorator#42), the next trick will be making the dependency on TelemetryRegistry optional. Strikes me registering the attribute myself is rude, which might introduce a race. Bah!

If your macro defined a José-style magic method eg. __telemetry_registry_details__/0 in the module exposing the results of Module.get_attribute/3, though, I could do the same in an API-compatible way using my own attribute. We'd each have to check Module.defines?(__MODULE__, {: __telemetry_registry_details__, 0}) and defoverridable __telemetry_registry_details__: 0 if so, bu— this is getting silly; maybe I should just invoke your macro. Thoughts?