Peep.Storage behaviour (peep v6.0.0)

View Source

Behaviour for Peep storage backends. These functions are mainly called by Peep during normal functioning. Ordinary usage of Peep should not require calling any of these functions.

An implementation of Peep.Storage must implement one of:

When Peep starts, it will see which of the above callbacks is exported, and :telemetry event handlers will call the exported function.

Unless you have a good reason (e.g. your Peep.Storage implementation uses NIFs), prefer insert_metric/5. insert_metrics/3 builds a list with one tuple per metric for each event, which only pays off when a call into the backend is expensive enough to be worth amortizing.

Summary

Callbacks

get_all_metrics(term, persistent)

Retrieves all stored metrics

insert_metric(storage, metric_id, t, value, tags)

Stores a single sample.

insert_metrics(storage, tag_results, list)

Stores every sample belonging to a single telemetry event.

new(term)

Creates a new term representing a Peep storage backend.

prune_tags(term, list)

Removes metrics whose metadata contains a specific tag key and value. This is intended to improve situations where Peep emits metrics whose tags have high cardinality.

register_metrics(storage, ids_to_metrics)

Called once when Peep starts to inform a backend about Peep's metrics.

resolve(term)

Resolves storage to its per-scheduler form for the current scheduler. Called once per event to avoid redundant scheduler lookups across metrics.

storage_size(term)

Calculates the amount of memory used by a Peep storage backend.

Callbacks

get_all_metrics(term, persistent)

@callback get_all_metrics(term(), persistent()) :: map()

Retrieves all stored metrics

insert_metric(storage, metric_id, t, value, tags)

(optional) 
@callback insert_metric(
  storage :: term(),
  Peep.metric_id(),
  Telemetry.Metrics.t(),
  value :: number(),
  tags :: map()
) :: any()

Stores a single sample.

Called once per metric of an event.

insert_metrics(storage, tag_results, list)

(optional) 
@callback insert_metrics(
  storage :: term(),
  tag_results :: tuple(),
  [
    {Peep.metric_id(), Telemetry.Metrics.t(), number(),
     tag_idx :: non_neg_integer()}
  ]
) :: any()

Stores every sample belonging to a single telemetry event.

A sample's tags are elem(tag_results, tag_idx).

new(term)

@callback new(term()) :: term()

Creates a new term representing a Peep storage backend.

prune_tags(term, list)

@callback prune_tags(term(), [%{required(Telemetry.Metrics.tag()) => term()}]) :: :ok

Removes metrics whose metadata contains a specific tag key and value. This is intended to improve situations where Peep emits metrics whose tags have high cardinality.

register_metrics(storage, ids_to_metrics)

(optional) 
@callback register_metrics(
  storage :: term(),
  ids_to_metrics :: ids_to_metrics()
) :: :ok

Called once when Peep starts to inform a backend about Peep's metrics.

Each distribution carries :peep_buckets: unique {boundary, upper_bound} pairs of floats sorted by boundary. A sample below boundary, and not below the boundary before it, belongs to that bucket. A distribution's series is keyed by upper_bound, which is what the exporters report.

The two can differ: for Peep.Buckets.Exponential, boundary is the smallest float above the bucket, a few floats away from upper_bound.

resolve(term)

@callback resolve(term()) :: term()

Resolves storage to its per-scheduler form for the current scheduler. Called once per event to avoid redundant scheduler lookups across metrics.

storage_size(term)

@callback storage_size(term()) :: %{size: non_neg_integer(), memory: non_neg_integer()}

Calculates the amount of memory used by a Peep storage backend.