Module exometer

Description
Data Types
Function Index
Function Details

API and behaviour for metrics instances.

Description

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.

Data Types

behaviour()


behaviour() = probe | entry

datapoint()


datapoint() = atom() | integer()

entry()


entry() = #exometer_entry{}

error()


error() = {error, any()}

info()


info() = name | type | module | value | cache | status | timestamp | options | ref | datapoints | entry

name()


name() = list()

options()


options() = [{atom(), any()}]

status()


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()}

value()


value() = any()

Function Index

aggregate/2	Aggregate datapoints of matching entries.
create_entry/1
delete/1	Delete the metric.
ensure/3	Ensure that metric exists and is of given type.
find_entries/1	Find metrics based on a name prefix pattern.
get_value/1	Fetch the current value of the metric.
get_value/2
get_values/1
global_status/1
info/1	Returns a list of info items for Metric, see `info/2`.
info/2	Retrieves information about a metric.
new/2	Equivalent to `new(Name, Type, [])`.
new/3	Create a new metrics entry.
propose/3	Propose a new exometer entry (no entry actually created).
re_register/3	Create a new metrics entry, overwrite any old entry.
register_application/0	Equivalent to `register_application(current_application())`.
register_application/1	Registers statically defined entries with exometer.
repair/1	Delete and re-create an entry.
reset/1	Reset the metric.
sample/1	Tells the metric (mainly probes) to take a sample.
select/1	Perform an `ets:select()` on the set of metrics.
select/2	Perform an `ets:select()` with a Limit on the set of metrics.
select_cont/1	Equivalent to `ets:select(Cont)`.
select_count/1	Corresponds to `ets:select_count/1`.
setopts/2	Change options for the metric.
start/0	Start exometer and dependent apps (for testing).
stop/0	Stop exometer and dependent apps (for testing).
update/2	Update the given metric with `Value`.
update_or_create/2	Update existing metric, or create+update according to template.
update_or_create/4

Function Details

aggregate/2


aggregate(Pattern::ets:match_spec(), DataPoints::[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}]}

create_entry/1

create_entry(Exometer_entry) -> any()

delete/1


delete(Name::name()) -> ok | error()

Delete the metric

ensure/3


ensure(Name::name(), Type::type(), Opts::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.

find_entries/1


find_entries(Path::[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}].

get_value/1


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

get_value/2


get_value(Name::name(), DataPoint::datapoint() | [datapoint()]) -> {ok, value()} | {error, not_found}

get_values/1

get_values(Path) -> any()

global_status/1

global_status(St) -> any()

info/1


info(Name::name()) -> [{info(), any()}] | undefined

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

info/2


info(Exometer_entry::name(), Item::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

new/2


new(Name::name(), Type::type()) -> ok

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

new/3


new(Name::name(), Type::type(), Opts::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).

propose/3


propose(Name::name(), Type::type(), Opts::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).

re_register/3


re_register(Name::name(), Type::type(), Opts::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.

register_application/0


register_application() -> ok | error()

Equivalent to register_application(current_application()).

register_application/1


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.

repair/1


repair(Name::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.

reset/1


reset(Name::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.

sample/1


sample(Name::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.

select/1


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

select/2


select(Pattern::ets:match_spec(), Limit::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.

select_cont/1


select_cont(Cont::$end_of_table | tuple()) -> $end_of_table | {[{name(), type(), status()}], _Cont}

Equivalent to ets:select(Cont).

select_count/1


select_count(Pattern::ets:match_spec()) -> non_neg_integer()

Corresponds to ets:select_count/1.

setopts/2


setopts(Name::name(), Options::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/0

start() -> any()

Start exometer and dependent apps (for testing).

stop/0

stop() -> any()

Stop exometer and dependent apps (for testing).

update/2


update(Name::name(), Value::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.

update_or_create/2


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.

update_or_create/4

update_or_create(Name, Value, Type, Opts) -> any()

Files

exometer.md

Latest commit

History