View Source exometer_alias (exometer_core v1.7.1)

API and behaviour for metrics instances This module implements an alias registry for exometer metrics. An alias can be either an atom or a binary, and maps to an entry+datapoint pair. The registry is an ordered set with binary keys, enabling straight lookup, prefix match/fold and regexp fold.

The purpose of the registry is to support mapping of 'legacy names' to exometer metrics, where the legacy names don't conform to the exometer naming standard.

Summary

Functions

Delete an alias, if it exists in the registry.

Resolve the given alias and return corresponding metric and value.

Load a list of mappings between entry+datapoint pairs and aliases.

Create a new alias.

Fold (ascending order) over the aliases matching Prefix.

Fold (descending order) over the aliases matching Prefix.

List all aliases matching the given prefix.

Fold (ascending order) over the aliases matching Regexp.

Fold (descending order) over the aliases matching Regexp.

Look up an alias in the registry and return corresponding mapping.

List all aliases mapped to the given entry+datapoint pair(s).

Unload a list of mappings.

Resolves the given alias and updates the corresponding entry (if any).

Types

-type acc() :: any().
-type alias() :: atom() | binary().
-type dp() :: exometer:datapoint().
-type fold_fun() :: fun((alias(), name(), dp(), acc()) -> acc()).
-type mp() :: {re_pattern, _, _, _, _}.
-type name() :: exometer:name().
-type reason() :: any().
-type regexp() :: iodata() | mp().
-type stat_map() :: [{name(), [{dp(), alias()}]}].

Functions

-spec delete(alias()) -> ok.

Delete an alias, if it exists in the registry.

This function will delete an alias if it exists in the registry. It will return ok signaling that after completion, the alias is no longer in the registry.
-spec get_value(alias()) -> {ok, any()} | {error, any()}.

Resolve the given alias and return corresponding metric and value.

The function returns {ok, Value} or {error, not_found} depending on whether there is a 'live' mapping (i.e. the entry refered to by the alias also exists.)
-spec load(fun(() -> stat_map())) -> ok.

Load a list of mappings between entry+datapoint pairs and aliases.

This operation will overwrite any aliases with the same name that already exist. The argument is a fun (zero arity) that returns a list of {EntryName, [{DataPoint, Alias}]} tuples.
-spec new(alias(), name(), dp()) -> ok | {error, reason()}.

Create a new alias.

This function maps an alias to an entry name and datapoint. Each alias maps to exactly one entry+datapoint pair. The entry does not need to exist when the alias is registered.

The function raises an exception if the arguments are of the wrong type, and returns {error, exists} if the alias has already been registered.
Link to this function

prefix_foldl(Prefix, F, Acc)

View Source
-spec prefix_foldl(binary(), fold_fun(), acc()) -> acc().

Fold (ascending order) over the aliases matching Prefix.

The fold function is called with F(Alias, Entry, Datapoint). Note that the referenced entry may not yet be created.
Link to this function

prefix_foldr(Pattern, F, Acc)

View Source
-spec prefix_foldr(binary(), fold_fun(), acc()) -> acc().

Fold (descending order) over the aliases matching Prefix.

The fold function is called with F(Alias, Entry, Datapoint). Note that the referenced entry may not yet be created.
-spec prefix_match(binary()) -> [{alias(), name(), dp()}].

List all aliases matching the given prefix.

Even if the alias is an atom, prefix matching will be performed. Note that the referenced entries may not yet be created.
Link to this function

regexp_foldl(Regexp, F, Acc)

View Source
-spec regexp_foldl(regexp(), fold_fun(), acc()) -> acc().

Fold (ascending order) over the aliases matching Regexp.

The fold function is called with F(Alias, Entry, Datapoint). Note that the referenced entry may not yet be created.

In order to avoid scanning the whole registry, a prefix is extracted from the regular expression. For a non-empty prefix, make sure to anchor the regular expression to the beginning of the name (e.g. "^my_stats.*").
Link to this function

regexp_foldr(Pattern, F, Acc)

View Source
-spec regexp_foldr(regexp(), fold_fun(), acc()) -> acc().

Fold (descending order) over the aliases matching Regexp.

The fold function is called with F(Alias, Entry, Datapoint). Note that the referenced entry may not yet be created.

In order to avoid scanning the whole registry, a prefix is extracted from the regular expression. For a non-empty prefix, make sure to anchor the regular expression to the beginning of the name (e.g. "^my_stats.*").
-spec resolve(alias()) -> {name(), dp()} | error.

Look up an alias in the registry and return corresponding mapping.

This function returns {EntryName, Datapoint} corresponding to the given alias, or error if no corresponding mapping exists.
Link to this function

reverse_map(Name, Datapoint)

View Source
-spec reverse_map(name() | '_', dp() | '_') -> [{alias(), name(), dp()}].

List all aliases mapped to the given entry+datapoint pair(s).

Match spec-style wildcards can be used for Name and/or Datapoint.
-spec unload(fun(() -> stat_map())) -> ok.

Unload a list of mappings.

A mapping will only be deleted if the given alias+entry+datapoint matches what is in the registry. The argument is of the same type as for load/1.
-spec update(alias(), any()) -> ok | {error, any()}.

Resolves the given alias and updates the corresponding entry (if any).

This function can be seen as a wrapper to exometer:update/2. Although the alias maps to a given datapoint, the entry itself is updated, so any alias mapping to the same entry can be used with the same result.