Skip to content

Commit

Permalink
Some doc cleanup to cater to ex_doc
Browse files Browse the repository at this point in the history
  • Loading branch information
uwiger committed Feb 17, 2024
1 parent cb8ab17 commit 9909827
Show file tree
Hide file tree
Showing 8 changed files with 240 additions and 266 deletions.
60 changes: 30 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

Copyright (c) 2014 Basho Technologies, Inc. All Rights Reserved.

__Version:__ Feb 17 2024 13:59:12
__Version:__ Feb 17 2024 15:18:00

__Authors:__ Ulf Wiger ([`[email protected]`](mailto:[email protected])), Magnus Feuer ([`[email protected]`](mailto:[email protected])).

Expand Down Expand Up @@ -88,8 +88,8 @@ Metrics are identified by a list of terms, such as given below:
`[ xml_front_end, parser, file_size ]`

A metric is created through a call by the code to be instrumented to
`exometer:new()`. Once created, the metric can be updated through
`exometer:update()`, or on its own initiative through the
`exometer:new/2`. Once created, the metric can be updated through
`exometer:update/2`, or on its own initiative through the
`exometer_probe:sample` behavior implementation.


Expand All @@ -113,7 +113,7 @@ given metric.
#### <a name="Metric_Type">Metric Type</a> ####

The type of a metric, specified when the metric is created through
`exometer:new()`, determines which `exometer_entry`
`exometer:new/2`, determines which `exometer_entry`
callback to use.

The link between the type and the entry to use is configured
Expand All @@ -127,7 +127,7 @@ configurable `exometer_entry` callback.
#### <a name="Entry_Callback">Entry Callback</a> ####

An exometer entry callback will receive values reported to a metric through the
`exometer:update()` call and compile it into one or more data points.
`exometer:update/2` call and compile it into one or more data points.
The entry callback can either be a counter (implemented natively
in `exometer`), or a more complex statistical analysis such
as a uniform distribution or a regular histogram.
Expand All @@ -153,7 +153,7 @@ the given subsystem and add it to the metric's data points.

#### <a name="Caching">Caching</a> ####

Metric and data point values are read with the `exometer:get_value()`
Metric and data point values are read with the `exometer:get_value/1`
function. In the case of counters, this operation is very fast. With probes,
the call results in a synchronous dialog with the probe process, and the
cost of serving the request depends on the probe implementation and the
Expand All @@ -162,12 +162,12 @@ nature of the metric being served.
If the cost of reading the value is so high that calling the function often
would result in prohibitive load, it is possible to cache the value. This is
done either explicitly from the probe itself (by calling
`exometer_cache:write()`), or by specifying the option `{cache, Lifetime}`
`exometer_cache:write/3`), or by specifying the option `{cache, Lifetime}`
for the entry. If an entry has a non-zero cache lifetime specified, the
`get_value()` call will try fetching the cached value before calling the
`get_value/1` call will try fetching the cached value before calling the
actual entry and automatically caching the result.

Note that if `{cache, Lifetime}` is not specified, `exometer:get_value()`
Note that if `{cache, Lifetime}` is not specified, `exometer:get_value/1`
will neither read nor write to the cache. It is possible for the probe
to periodically cache a value regardless of how the cache lifetime is set,
and the probe may also explicitly read from the cache if it isn't done
Expand All @@ -185,15 +185,15 @@ Each subscription ties a specific metric-datapoint pair to a reporter
and an interval (given in milliseconds). The reporter system will, at
the given interval, send the current value of the data point to the
subscribing reporter. The subscription, with all its parameters,
is setup through a call to `exometer_report:subscribe()`.
is setup through a call to `exometer_report:subscribe/4`.

In the case of processes, subscribed-to values will be delivered as a
message. Modules, which implement the `exometer_report` callback
behavior, will receive the plugins as a callbacks within the
`exometer_report` process.

Subscriptions can either be setup at runtime, through
`exometer_report:subscribe()` calls, or statically through the
`exometer_report:subscribe/4` calls, or statically through the
`exometer_report` configuration data.


Expand All @@ -206,10 +206,10 @@ with the Exometer Core package, as described below:
#### <a name="counter_(exometer_native)">counter (exometer native)</a> ####

The counter is implemented directly in `exometer` to provide simple
counters. A call to `exometer:update()` will add the provided value
counters. A call to `exometer:update/2` will add the provided value
to the counter.

The counter can be reset to zero through `exometer:reset()`.
The counter can be reset to zero through `exometer:reset/1`.

The available data points under a metric using the counter entry
are `value` and `ms_since_reset`.
Expand All @@ -224,10 +224,10 @@ comparison to the regular counter.
The tradeoff is that running tracing and/or debugging may interfere
with the counter functionality.

A call to `exometer:update()` will add the provided value to the
A call to `exometer:update/2` will add the provided value to the
counter.

The counter can be reset to zero through `exometer:reset()`.
The counter can be reset to zero through `exometer:reset/1`.

The available data points under a metric using the fast_counter
entry are `value` and `ms_since_reset`.
Expand All @@ -236,11 +236,11 @@ entry are `value` and `ms_since_reset`.
#### <a name="gauge_(exometer_native)">gauge (exometer native)</a> ####

The gauge is implemented directly in `exometer` to provide simple
gauges. A call to `exometer:update()` will set the gauge's value
gauges. A call to `exometer:update/2` will set the gauge's value
to the provided value. That is, the value of the gauge entry is
always the most recently provided value.

The gauge can be reset to zero through `exometer:reset()`.
The gauge can be reset to zero through `exometer:reset/1`.

The available data points under a metric using the gauge entry
are `value` and `ms_since_reset`.
Expand All @@ -249,7 +249,7 @@ are `value` and `ms_since_reset`.
#### <a name="exometer_histogram_(probe)">exometer_histogram (probe)</a> ####

The histogram probe stores a given number of updates, provided through
`exometer:update()`, in a histogram. The histogram maintains a log
`exometer:update/2`, in a histogram. The histogram maintains a log
derived from all values received during a configurable time span and
provides min, max, median, mean, and percentile analysis data points
for the stored data.
Expand All @@ -266,7 +266,7 @@ resource consumption.
#### <a name="exometer_uniform_(probe)">exometer_uniform (probe)</a> ####

The uniform probe provides a uniform sample over a pool of values
provided through `exometer:update()`. When the pool reaches its configurable
provided through `exometer:update/2`. When the pool reaches its configurable
max size, existing values will be replaced at random to make space for
new values. Much like `exometer_histogram`, the uniform probe
provides min, max, median, mean, and percentile analysis data points
Expand All @@ -277,7 +277,7 @@ for the stored data.

The spiral probe maintains the total sum of all values stored in its
histogram. The histogram has a configurable time span, all values
provided to the probe, through `exometer:update()`, within that time
provided to the probe, through `exometer:update/2`, within that time
span will be summed up and reported. If, for example, the histogram
covers 60 seconds, the spiral probe will report the sum of all
values reported during the last minute.
Expand All @@ -290,7 +290,7 @@ probe is also available.

The function entry allows for a simple caller-supplied function to be
invoked in order to retrieve non-exometer data. The
`exometer_function:get_value()` function will invoke a
`exometer_function:get_value/4` function will invoke a
`Module:Function(DataPoints)` call, where `Module` and
`Function` are provided by the caller.

Expand Down Expand Up @@ -358,25 +358,25 @@ under the given metric.

#### <a name="Deleting_metrics">Deleting metrics</a> ####

A metric previously created with `exometer:new()` can be deleted by
`exometer:delete()`.
A metric previously created with `exometer:new/2` can be deleted by
`exometer:delete/1`.

All subscriptions to the deleted metrics will be cancelled.


#### <a name="Setting_metric_values">Setting metric values</a> ####

A created metric can have its value updated through the
`exometer:update()` function:
`exometer:update/2` function:

```erlang

exometer:update(Name, Value)
```

The `Name` parameter is the same atom list provided to a previous
`exometer:new()` call. The `Value` is an arbitrarty element that is
forwarded to the `exometer:update()` function of the entry/probe that the
`exometer:new/2` call. The `Value` is an arbitrarty element that is
forwarded to the `exometer:update/2` function of the entry/probe that the
metric is mapped to.

The receiving entry/probe will process the provided value and modify
Expand All @@ -395,8 +395,8 @@ exometer:info(Name, datapoints)
```

The `Name` parameter is the same atom list provided to a previous
`exometer:new()` call. The call will return a list of data point
atoms that can then be provided to `exometer:get_value()` to
`exometer:new/2` call. The call will return a list of data point
atoms that can then be provided to `exometer:get_value/1` to
retrieve their actual value:

```erlang
Expand Down Expand Up @@ -554,7 +554,7 @@ called during upgrade, as it will re-apply the settings each time.
#### <a name="Configuring_static_subscriptions">Configuring static subscriptions</a> ####

Static subscriptions, which are automatically setup at exometer
startup without having to invoke `exometer_report:subscribe()`, are
startup without having to invoke `exometer_report:subscribe/4`, are
configured through the report sub section under exometer.

Below is an example, from `exometer/priv/app.config`:
Expand Down Expand Up @@ -602,7 +602,7 @@ The meaning of the above tuple elements is:
+ `Reporter :: module()`<br />Specifies the reporter plugin module, such as`exometer_report_collectd` that is to receive updated metric's data
points.

+ `Metric :: [atoms()]`<br />Specifies the path to a metric previously created with an`exometer:new()` call.
+ `Metric :: [atoms()]`<br />Specifies the path to a metric previously created with an`exometer:new/2` call.

+ `DataPoint` :: atom() | [atom()]'<br />Specifies the data point within the given metric to send to the
receiver. The data point must match one of the data points returned by`exometer:info(Name, datapoints)` for the given metrics name.
Expand Down
Loading

0 comments on commit 9909827

Please sign in to comment.