exometer_alias.md

Module exometer_alias

• Description
• Data Types
• Function Index
• Function Details

API and behaviour for metrics instances This module implements an alias registry for exometer metrics.

Behaviours: gen_server.

Description

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.

Data Types

acc()

acc() = any()

alias()

alias() = atom() | binary()

dp()

dp() = exometer:datapoint()

fold_fun()

fold_fun() = fun((alias(), name(), dp(), acc()) -> acc())

mp()

mp() = {re_pattern, term(), term(), term(), term()}

name()

name() = exometer:name()

reason()

reason() = any()

regexp()

regexp() = iodata() | mp()

stat_map()

stat_map() = [{name(), [{dp(), alias()}]}]

Function Index

check_map/1
delete/1	Delete an alias, if it exists in the registry.
get_value/1	Resolve the given alias and return corresponding metric and value.
load/1	Load a list of mappings between entry+datapoint pairs and aliases.
new/3	Create a new alias.
prefix_foldl/3	Fold (ascending order) over the aliases matching Prefix.
prefix_foldr/3	Fold (descending order) over the aliases matching Prefix.
prefix_match/1	List all aliases matching the given prefix.
regexp_foldl/3	Fold (ascending order) over the aliases matching Regexp.
regexp_foldr/3	Fold (descending order) over the aliases matching Regexp.
resolve/1	Look up an alias in the registry and return corresponding mapping.
reverse_map/2	List all aliases mapped to the given entry+datapoint pair(s).
start_link/0
unload/1	Unload a list of mappings.
update/2	Resolves the given alias and updates the corresponding entry (if any).

Function Details

check_map/1

check_map(Map) -> any()

delete/1

delete(Alias::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.

get_value/1

get_value(Alias::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.)

load/1

load(Fun::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.

new/3

new(Alias::alias(), Entry::name(), DP::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.

prefix_foldl/3

prefix_foldl(Prefix::binary(), F::fold_fun(), Acc::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.

prefix_foldr/3

prefix_foldr(Pattern::binary(), F::fold_fun(), Acc::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.

prefix_match/1

prefix_match(Pattern::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.

regexp_foldl/3

regexp_foldl(Regexp::regexp(), F::fold_fun(), Acc::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.*").

regexp_foldr/3

regexp_foldr(Pattern::regexp(), F::fold_fun(), Acc::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.*").

resolve/1

resolve(Alias::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.

reverse_map/2

reverse_map(Name::name() | _, Datapoint::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.

start_link/0

start_link() -> any()

unload/1

unload(Fun::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.

update/2

update(Alias::alias(), Value::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.