View Source Uplink.Monitor behaviour (uplink v0.3.0)

A behaviour module for implementing a library or application monitor.

Uplink Monitors provide a template for the most common requirements to instrument a library or application in a consistent manner. These provide a simple abstraction for building standard observability patterns for whatever is being monitored while removing the need for users to repeatedly define and configure things like TelemetryMetrics definitions.

There are three required callbacks which make up a monitor. The provided macro provides default implementations for each, allowing you to only implement what is needed for a particular monitor.

Each callback receives the same argument defined in Uplink.monitor/0.

Usage

defmodule MyApp.CustomMonitor do
  using Uplink.Monitor
  # override any callbacks you need

  @impl true
  def init(_) do
    # some setup
    :ok
  end

  @impl true
  def metric_definitions(_) do
    [Telemetry.Metrics.counter("some.event")]
  end

  @impl true
  def poller_specs(_) do
    [
      {:timer.seconds(5), [
        {MyApp.Telemetry, :emit_stats, []}
      ]}
    ]
end

See Uplink.Monitors.VM for an example implementation.

Summary

Callbacks

Invoked when Uplink is starting.

Invoked when Uplink is starting.

Invoked when Uplink is starting.

Callbacks

@callback init(args :: any()) :: :ok | :error

Invoked when Uplink is starting.

It is useful for initializing any custom monitoring for the library or application being monitored. Examples include creating telemetry handlers to log slow Ecto queries which exceed a threshold or starting an OpenTelemetry bridge library.

If the function returns :error, Uplink will exit.

This callback is required.

Link to this callback

metric_definitions(args)

View Source
@callback metric_definitions(args :: any()) :: Uplink.metric_definitions()

Invoked when Uplink is starting.

It is useful for providing a standard set of Telemetry.Metrics.t/0 definitions for the library or application being monitored.

This callback is required.

@callback poller_specs(args :: any()) :: Uplink.poller_specs()

Invoked when Uplink is starting.

It is useful for providing a standard set of telemetry_pollers for the library or application being monitored. Examples include emitting cache sizes, memory usage, or process counts.

This callback is required.