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.
Ensure that metric exists and is of given type.
Find metrics based on a name prefix pattern.
Fetch the current value of the metric.
info/2
.Retrieves information about a metric.
Equivalent to new(Name, Type, []).
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.
Equivalent to ets:select(Cont).
ets:select_count/1
.Change options for the metric.
Update the given metric with Value
.
Update existing metric, or create+update according to template.
Types
Functions
-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}]}
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 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.
[{Name, Type, Status}]
.
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.info/2
.
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
Equivalent to new(Name, Type, []).
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.)
"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).
-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 asnew/3
, but not actually creating the entry. The return value, if successful, corresponds to exometer_info:pp(Entry)
.
Create a new metrics entry, overwrite any old entry.
This function behaves asnew/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()).
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.
-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.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.
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 returnok
.
-spec select(ets:match_spec()) -> list().
Perform an ets:select()
on the set of metrics.
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.
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().
ets:select_count/1
.
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.
{status, enabled}
, which will enable the metric and cause other options to be processed.
Update the given metric with Value
.
ok
will be returned without any other action being taken.
Update existing metric, or create+update according to template.
If the metric exists, it is updated (seeupdate/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.