View Source exometer (exometer_core v1.7.1)

API and behaviour for metrics instances

Predefined templates

It is possible to define a set of defaults for exometer.

Example: Putting the following in a sys.config file,
  {exometer, [
           {defaults,
            [{['_'], function    , [{module, exometer_function}]},
             {['_'], counter     , [{module, exometer}]},
             {['_'], fast_counter, [{module, exometer}]},
             {['_'], gauge       , [{module, exometer}]},
             {['_'], histogram   , [{module, exometer_histogram}]},
             {['_'], spiral      , [{module, exometer_spiral}]}
            ]}
          ]}
  

will define global defaults for the given metric types. The format is {NamePattern, Type, Options}

The options can be overridden by options given in the new() command.

NamePattern is similar to that used in find_entries/1. For more information, see exometer_admin:set_default/3.

Summary

Functions

Aggregate datapoints of matching entries.

Delete the metric

Ensure that metric exists and is of given type.

Find metrics based on a name prefix pattern.

Fetch the current value of the metric.

Returns a list of info items for Metric, see info/2.

Retrieves information about a metric.

Create a new metrics entry.

Propose a new exometer entry (no entry actually created).

Create a new metrics entry, overwrite any old entry.

Registers statically defined entries with exometer.

Delete and re-create an entry.

Reset the metric.

Tells the metric (mainly probes) to take a sample.

Perform an ets:select() on the set of metrics.

Perform an ets:select() with a Limit on the set of metrics.

Corresponds to ets:select_count/1.

Change options for the metric.

Start exometer and dependent apps (for testing).
Stop exometer and dependent apps (for testing).

Update the given metric with Value.

Update existing metric, or create+update according to template.

Types

-type behaviour() :: probe | entry.
-type datapoint() :: atom() | integer().
-type entry() ::
    #exometer_entry{name :: term(),
                    type :: term(),
                    behaviour :: term(),
                    module :: term(),
                    status :: term(),
                    cache :: term(),
                    value :: term(),
                    timestamp :: term(),
                    options :: term(),
                    ref :: term()}.
-type error() :: {error, any()}.
-type info() ::
    name | type | module | value | cache | status | timestamp | options | ref | datapoints | entry.
-type name() :: list().
-type options() :: [{atom(), any()}].
-type status() :: enabled | disabled.
-type type() ::
    atom() |
    {function, M :: atom(), F :: atom()} |
    {function, M :: atom(), F :: atom(), ArgSpec :: list(), Type :: atom(), DataPoints :: list()} |
    {Type :: atom(), Arg :: any()}.
-type value() :: any().

Functions

Link to this function

aggregate(Pattern, DataPoints)

View Source
-spec aggregate(ets:match_spec(), [datapoint()]) -> list().

Aggregate datapoints of matching entries.

This function selects metric entries based on the given match spec, and summarizes the given datapoint values.

Note that the match body of the match spec will be overwritten, to produce only the value for each entry matching the head and guard pattern(s).

The function can for example be used inside a function metric:

  1> exometer:start().
  ok
  2> exometer:new([g,1], gauge, []).
  ok
  3> exometer:new([g,2], gauge, []).
  ok
  4> exometer:new([g,3], gauge, []).
  ok
  5> [exometer:update(N,V) || {N,V} <- [{[g,1],3}, {[g,2],4}, {[g,3],5}]].
  [ok,ok,ok]
  6> exometer:new([g], {function,exometer,aggregate,
                        [ [{{[g,'_'],'_','_'},[],[true]}], [value] ],
                        value, [value]}, []).
  ok
  7> exometer:get_value([g], [value]).
  {ok,[{value,12}]}
  
Link to this function

create_entry(Exometer_entry)

View Source
-spec delete(name()) -> ok | error().
Delete the metric
Link to this function

ensure(Name, Type, Opts)

View Source
-spec ensure(name(), type(), options()) -> ok | error().

Ensure that metric exists and is of given type.

This function is similar to re-register, but doesn't actually re-register a metric if it already exists. If a matching entry is found, a check is performed to verify that it is of the correct type. If it isn't, an error tuple is returned.
-spec find_entries([any() | '_']) -> [{name(), type(), status()}].

Find metrics based on a name prefix pattern.

This function will find and return metrics whose name matches the given prefix. For example [kvdb, kvdb_conf, Table] would match any metrics tied to the given table in the kvdb_conf database.

It is possible to insert wildcards: [kvdb, kvdb_conf, '_', write] would match write-related metrics in all tables of the kvdb_conf database.

The format of the returned metrics is [{Name, Type, Status}].
-spec get_value(name()) -> {ok, value()} | {error, not_found}.

Fetch the current value of the metric.

For a built-in counter, the value returned is the sum of all counter instances (one per scheduler). For plugin metrics, the callback module is responsible for providing the value. If the metric has a specified (non-zero) cache lifetime, and a value resides in the cache, the cached value will be returned.
Link to this function

get_value(Name, DataPoint)

View Source
-spec get_value(name(), datapoint() | [datapoint()]) -> {ok, value()} | {error, not_found}.
-spec info(name()) -> [{info(), any()}] | undefined.
Returns a list of info items for Metric, see info/2.
Link to this function

info(Exometer_entry, Item)

View Source
-spec info(name(), info()) -> any().

Retrieves information about a metric.

Supported info items:

* name - The name of the metric * type - The type of the metric * module - The callback module used * value - The result of get_value(Name) * cache - The cache lifetime * status - Operational status: enabled or disabled * timestamp - When the metric was last reset/initiated * datapoints - Data points available for retrieval with get_value() * options - Options passed to the metric at creation (or via setopts()) * ref - Instance-specific reference; usually a pid (probe) or undefined
-spec new(name(), type()) -> ok.

Equivalent to new(Name, Type, []).

-spec new(name(), type(), options()) -> ok.

Create a new metrics entry.

Name must be a list of terms (e.g. atoms). Type must be either one of the built-in types, or match a predefined template.

Options will be passed to the entry, but the framework will recognize the following options:

* {cache, Lifetime} - Cache the results of get_value/1 for the given number of milliseconds. Subsequent calls to get_value/1 will get the cached value, if found. Default is 0, which means no caching will be performed.

* {status, enabled | disabled} - Default is enabled. If the metric is disabled, calls to get_value/1 will return {ok, disabled}, and calls to update/2 and sample/1 will return ok but will do nothing.

* {snmp, [{DataPoint, ReportInterval}]} - defines a link to SNMP reporting, where the given data points are sampled at the given intervals, converted to SNMP PDUs and transmitted via the exometer_report_snmp reporter.

* {snmp_syntax, [{DataPoint | {default}, SYNTAX}]} - specifies a custom SNMP type for a given data point. SYNTAX needs to be a binary or a string, and corresponds to the SYNTAX definition in the generated SNMP MIB.

* {aliases, [{DataPoint, Alias}]} - maps aliases to datapoints. See exometer_alias:new/2.

* {'--', Keys} removes option keys from the applied template. This can be used to clean up the options list when overriding the defaults for a given namespace (if the default definition contains options that are not applicable, or would even cause problems with the current entry.)

For example, the default value for an exometer counter is "Counter32", which expands to SYNTAX Counter32 in the corresponding MIB object definition. If a 64-bit counter (not supported by SNMPv1) is desired instead, the option {snmp_syntax, [{value, "Counter64"}]} can be added to the counter entry (note that value in this case is the name of the data point representing the counter value).
Link to this function

propose(Name, Type, Opts)

View Source
-spec propose(name(), type(), options()) -> exometer_info:pp() | error().

Propose a new exometer entry (no entry actually created).

This function analyzes a proposed entry definition, applying templates and processing options in the same way as new/3, but not actually creating the entry. The return value, if successful, corresponds to exometer_info:pp(Entry).
Link to this function

re_register(Name, Type, Opts)

View Source
-spec re_register(name(), type(), options()) -> ok.

Create a new metrics entry, overwrite any old entry.

This function behaves as new/3, but will not fail if an entry with the same name already exists. Instead, the old entry will be replaced by the new.
-spec register_application() -> ok | error().

Equivalent to register_application(current_application()).

Link to this function

register_application(_Application)

View Source
-spec register_application(_Application :: atom()) -> ok | error().

Registers statically defined entries with exometer.

This function can be used e.g. as a start phase hook or during upgrade. It will check for the environment variables exometer_defaults and exometer_predefined in Application, and apply them as if it had when exometer was first started. If the function is called again, the settings are re-applied. This can be used e.g. during upgrade, in order to change statically defined settings.

If exometer is not running, the function does nothing.
-spec repair(name()) -> ok.

Delete and re-create an entry.

This function can be tried if a metric (e.g. a complex probe) has become 'stuck' or otherwise isn't functioning properly. It fetches the stored meta-data and then deletes and re-creates the metric.
-spec reset(name()) -> ok | error().

Reset the metric.

For a built-in counter, the value of the counter is set to zero. For other types of metric, the callback module will define exactly what happens when a reset() is requested. A timestamp (os:timestamp()) is saved in the exometer entry, which can be recalled using info/2, and will indicate the time that has passed since the metric was last reset.
-spec sample(name()) -> ok | error().

Tells the metric (mainly probes) to take a sample.

Probes often take care of data sampling using a configured sample interval. This function provides a way to explicitly tell a probe to take a sample. The operation is asynchronous. For other metrics, the operation likely has no effect, and will return ok.
-spec select(ets:match_spec()) -> list().

Perform an ets:select() on the set of metrics.

This function operates on a virtual structure representing the metrics, but otherwise works as a normal select(). The representation of the metrics is {Name, Type, Status}.
-spec select(ets:match_spec(), pos_integer() | infinity) -> {list(), _Cont}.

Perform an ets:select() with a Limit on the set of metrics.

This function is equivalent to select/1, but also takes a limit. After Limit number of matches, the function returns the matches and a continuation, which can be passed to select_cont/1.
-spec select_cont('$end_of_table' | tuple()) -> '$end_of_table' | {[{name(), type(), status()}], _Cont}.

Equivalent to ets:select(Cont).

-spec select_count(ets:match_spec()) -> non_neg_integer().
Corresponds to ets:select_count/1.
-spec setopts(name(), options()) -> ok | error().

Change options for the metric.

Valid options are whatever the metric type supports, plus:

* {cache, Lifetime} - The cache lifetime (0 for no caching).

* {status, enabled | disabled} - the operational status of the metric.

Note that if the metric is disabled, setopts/2 will fail unless the options list contains {status, enabled}, which will enable the metric and cause other options to be processed.
Start exometer and dependent apps (for testing).
Stop exometer and dependent apps (for testing).
-spec update(name(), value()) -> ok | error().

Update the given metric with Value.

The exact semantics of an update will vary depending on metric type. For exometer's built-in counters, the counter instance on the current scheduler will be incremented. For a plugin metric (e.g. a probe), the corresponding callback module will be called. For a disabled metric, ok will be returned without any other action being taken.
Link to this function

update_or_create(Name, Value)

View Source
-spec update_or_create(Name :: name(), Value :: value()) -> ok | error().

Update existing metric, or create+update according to template.

If the metric exists, it is updated (see update/2). If it doesn't, exometer searches for a template matching Name, picks the best match and creates a new entry based on the template (see exometer_admin:set_default/3). Note that fully wild-carded templates (i.e. ['_']) are ignored.
Link to this function

update_or_create(Name, Value, Type, Opts)

View Source