PromEx Documentation

Telemetry is a library used by Elixir and Erlang applications to surface internal events. It allows libraries to emit events (such as the start of a task, completion of work, or an exception) which can then be consumed by attached callbacks.

Key Characteristics

• Pub/Sub Model: It functions like a synchronous pub/sub system. When an event is triggered, Telemetry dynamically dispatches to all registered callbacks for that specific event.
• Synchronous Execution: Callbacks are executed serially and synchronously. Because of this, callbacks must be kept extremely lightweight. If you need to perform blocking work or heavy processing in response to an event, you should offload that work to a separate Task or GenServer to avoid blocking the event emitter.
• Low Friction: It requires no global configuration. Events are identified by a list of atoms (e.g., [:my_app, :module, :event]), and callbacks are attached dynamically.

To create a custom PromEx plugin, your module must use the PromEx.Plugin module (which implements the PromEx behaviour). A plugin is used to load metrics for a dependent library or for internal application metrics.

Your module must implement one or more of the following optional callbacks:

• event_metrics(opts): For metrics triggered by specific events (e.g., HTTP requests).
• polling_metrics(opts): For metrics that are sampled at a regular interval.
• manual_metrics(opts): For metrics that are sampled once at startup and only updated when manually triggered.

Each callback should return a list of metric type structs (e.g., PromEx.MetricTypes.Polling) or a single struct. These structs contain a :metrics field which holds a list of Telemetry.Metrics definitions created via the Event.build/2, Polling.build/4, or Manual.build/3 functions.

defmodule MyApp.PromEx.Plugins.MyPlugin do
  use PromEx.Plugin

  @impl true
  def event_metrics(opts) do
    # ...
  end
end