From 990982748c83722b3f2d828f6420ecb537735c1a Mon Sep 17 00:00:00 2001 From: Ulf Wiger Date: Sat, 17 Feb 2024 15:22:03 +0100 Subject: [PATCH] Some doc cleanup to cater to ex_doc --- README.md | 60 ++++++++++----------- doc/README.md | 62 +++++++++++----------- doc/exometer_probe.md | 114 ++++++++++++++++++++-------------------- doc/exometer_report.md | 14 ++--- doc/overview.edoc | 58 ++++++++++---------- rebar.config | 25 ++++----- src/exometer_probe.erl | 114 ++++++++++++++++++++-------------------- src/exometer_report.erl | 59 ++++++--------------- 8 files changed, 240 insertions(+), 266 deletions(-) diff --git a/README.md b/README.md index f808389..5fdb332 100644 --- a/README.md +++ b/README.md @@ -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 ([`ulf.wiger@feuerlabs.com`](mailto:ulf.wiger@feuerlabs.com)), Magnus Feuer ([`magnus.feuer@feuerlabs.com`](mailto:magnus.feuer@feuerlabs.com)). @@ -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. @@ -113,7 +113,7 @@ given metric. #### Metric Type #### 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 @@ -127,7 +127,7 @@ configurable `exometer_entry` callback. #### Entry Callback #### 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. @@ -153,7 +153,7 @@ the given subsystem and add it to the metric's data points. #### Caching #### -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 @@ -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 @@ -185,7 +185,7 @@ 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 @@ -193,7 +193,7 @@ 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. @@ -206,10 +206,10 @@ with the Exometer Core package, as described below: #### counter (exometer native) #### 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`. @@ -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`. @@ -236,11 +236,11 @@ entry are `value` and `ms_since_reset`. #### gauge (exometer native) #### 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`. @@ -249,7 +249,7 @@ are `value` and `ms_since_reset`. #### exometer_histogram (probe) #### 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. @@ -266,7 +266,7 @@ resource consumption. #### exometer_uniform (probe) #### 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 @@ -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. @@ -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. @@ -358,8 +358,8 @@ under the given metric. #### Deleting metrics #### -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. @@ -367,7 +367,7 @@ All subscriptions to the deleted metrics will be cancelled. #### Setting metric values #### A created metric can have its value updated through the -`exometer:update()` function: +`exometer:update/2` function: ```erlang @@ -375,8 +375,8 @@ 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 @@ -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 @@ -554,7 +554,7 @@ called during upgrade, as it will re-apply the settings each time. #### Configuring static subscriptions #### 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`: @@ -602,7 +602,7 @@ The meaning of the above tuple elements is: + `Reporter :: module()`
Specifies the reporter plugin module, such as`exometer_report_collectd` that is to receive updated metric's data points. -+ `Metric :: [atoms()]`
Specifies the path to a metric previously created with an`exometer:new()` call. ++ `Metric :: [atoms()]`
Specifies the path to a metric previously created with an`exometer:new/2` call. + `DataPoint` :: atom() | [atom()]'
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. diff --git a/doc/README.md b/doc/README.md index 1bedd2b..280dc9e 100644 --- a/doc/README.md +++ b/doc/README.md @@ -4,11 +4,11 @@ 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 ([`ulf.wiger@feuerlabs.com`](mailto:ulf.wiger@feuerlabs.com)), Magnus Feuer ([`magnus.feuer@feuerlabs.com`](mailto:magnus.feuer@feuerlabs.com)). -[![CI workflow](https://github.com/github/docs/actions/workflows/main.yml/badge.svg)](https://github.com/github/docs/actions/workflows/main.yml) +[![Build Status](https://github.com/Feuerlabs/exometer_core/actions/workflows/main.yml/badge.svg)](https://github.com/Feuerlabs/exometer_core/actions/workflows/main.yml) [![Hex.pm Version][hex version badge]][hex] [![Hex.pm License][hex license badge]][hex] [![Build Tool][build tool]][hex] @@ -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. @@ -113,7 +113,7 @@ given metric. #### Metric Type #### 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 @@ -127,7 +127,7 @@ configurable `exometer_entry` callback. #### Entry Callback #### 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. @@ -153,7 +153,7 @@ the given subsystem and add it to the metric's data points. #### Caching #### -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 @@ -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 @@ -185,7 +185,7 @@ 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 @@ -193,7 +193,7 @@ 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. @@ -206,10 +206,10 @@ with the Exometer Core package, as described below: #### counter (exometer native) #### 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`. @@ -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`. @@ -236,11 +236,11 @@ entry are `value` and `ms_since_reset`. #### gauge (exometer native) #### 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`. @@ -249,7 +249,7 @@ are `value` and `ms_since_reset`. #### exometer_histogram (probe) #### 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. @@ -266,7 +266,7 @@ resource consumption. #### exometer_uniform (probe) #### 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 @@ -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. @@ -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. @@ -358,8 +358,8 @@ under the given metric. #### Deleting metrics #### -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. @@ -367,7 +367,7 @@ All subscriptions to the deleted metrics will be cancelled. #### Setting metric values #### A created metric can have its value updated through the -`exometer:update()` function: +`exometer:update/2` function: ```erlang @@ -375,8 +375,8 @@ 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 @@ -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 @@ -554,7 +554,7 @@ called during upgrade, as it will re-apply the settings each time. #### Configuring static subscriptions #### 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`: @@ -602,7 +602,7 @@ The meaning of the above tuple elements is: + `Reporter :: module()`
Specifies the reporter plugin module, such as`exometer_report_collectd` that is to receive updated metric's data points. -+ `Metric :: [atoms()]`
Specifies the path to a metric previously created with an`exometer:new()` call. ++ `Metric :: [atoms()]`
Specifies the path to a metric previously created with an`exometer:new/2` call. + `DataPoint` :: atom() | [atom()]'
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. diff --git a/doc/exometer_probe.md b/doc/exometer_probe.md index 5ed7f69..422dded 100644 --- a/doc/exometer_probe.md +++ b/doc/exometer_probe.md @@ -49,7 +49,7 @@ calls. Once running, the probe collects data from a subsystem, such as `/proc`, `sysfs`, and `netlink`, through timer-based calls to -`probe_sample/1` or explicit calls to `probe_update/2`. +`Mod:probe_sample/1` or explicit calls to `Mod:probe_update/2`. A probe implementation can support any number of data points, where each data point is a specifric sample from the probe. For @@ -57,7 +57,7 @@ example, a probe that measures network traffic would have `rx_packets`, `tx_packets`, `errors`, `dropped`, and other data points reported by `ifconfig(8)` and `ip(8)`. -Values are retrieved from the probe through the `probe_get_value/2` +Values are retrieved from the probe through the `Mod:probe_get_value/2` call, which specifies the data points to be returned. The probe is expected to gather the given data points and return them to the caller. @@ -71,7 +71,7 @@ implementation. #### behaviour/0 #### -The `behaviour/0` function for an entry implementation should return +The `Mod:behaviour/0` function for an entry implementation should return the atom `probe`. This function will be involved by the exometer system in order to determine if a callback is an entry or a probe. @@ -79,7 +79,7 @@ an entry or a probe. #### probe_init/3 #### -The `probe_init/3` function is invoked as follows: +The `Mod:probe_init/3` function is invoked as follows: ```erlang @@ -87,8 +87,8 @@ The `probe_init/3` function is invoked as follows: ``` The implementation shall initiate the probe, create the -necessary state, and return it for furure access -through `probe_update/2`, `probe_sample/1` and `get_value/2` calls. +necessary state, and return it for future access +through `Mod:probe_update/2`, `Mod:probe_sample/1` and `Mod:probe_get_value/2` calls. The arguments are as follows: @@ -104,10 +104,10 @@ different types are mapped to the same probe module. Specifies an option list that contains additional setup directives to the probe. The actual options to support are a combination of the standard options, described below, and probe specific options -processed by `probe_init/3`. +processed by `Mod:probe_init/3`. Standard options are processed directly by `new/3`, before -`probe_init/3` is calledm and are as follows: +`Mod:probe_init/3` is called, and are as follows: + `{priority, P}` Will be forwarded by the probe's process to `erlang:process_flag/2`. @@ -125,27 +125,27 @@ Will be forwarded by the probe's process to `erlang:process_flag/2`. Specifies the interval, in milliseconds, that `exometer_probe:sample/1`. should be invoked at. -The `probe_init/3` implementation is invoked by `exometer:new/3`, +The `Mod:probe_init/3` implementation is invoked by `exometer:new/3`, which calls `exometer_probe:new/3`, which invokes the probe implementation.. -The `probe_init/3` function shall return `{ok, State}` where State +The `Mod:probe_init/3` function shall return `{ok, State}` where State is a tuple that will be provided as a the `State` argument to all future probe implementation calls for the metric. If the `sample_interval` option has been specified in `Opts`, -probe_sample/2' will be invoked immediately after `probe_init/2` -returns to retrieve a first sample. After that, `probe_sample/2` +`Mod:probe_sample/2` will be invoked immediately after `Mod:probe_init/2` +returns to retrieve a first sample. After that, `Mod:probe_sample/2` will repeatedly will be called by the probe process at the millisecond-specified interval. -Should `probe_init/3` return antyhing else but `{ok, State}`, +Should `Mod:probe_init/3` return antyhing else but `{ok, State}`, invoking `new/3` call will fail. #### probe_terminate/1 #### -The `probe_terminate/1` function is invoked as follows: +The `Mod:probe_terminate/1` function is invoked as follows: ```erlang @@ -158,31 +158,31 @@ given state and return `ok`. The arguments are as follows: + `State` -The probe state, originally returned by `probe_init/3` and subsequentially +The probe state, originally returned by `Mod:probe_init/3` and subsequentially modified by other probe implementation calls. -The `probe_terminate/1` implementation is invoked by `exometer:delete/1`, which +The `Mod:probe_terminate/1` implementation is invoked by `exometer:delete/1`, which calls `exometer_probe:delete/3`, which invokes the probe implementation. #### probe_setopts/3 #### -The `probe_setopts/2` function is invoked as follows: +The `Mod:probe_setopts/2` function is invoked as follows: ```erlang probe_setopts(Entry, Opts, State) ``` -The `probe_setopts/4` implementation is invoked by +The `Mod:probe_setopts/4` implementation is invoked by `exometer:setopts/3`, which calls `exometer_probe:setopts/3`, which invokes the probe implementation. The implementation of this function shall modify the options of a probe. The `setopts/3` function, which will process standard -options before invoking `probe_setopts/4` with the remaining -options. See the documentation for `probe_init/3` for details. +options before invoking `Mod:probe_setopts/4` with the remaining +options. See the documentation for `Mod:probe_init/3` for details. The arguments are as follows: @@ -197,7 +197,7 @@ The probe-specific options to be processed. The new status of the entry. + `State` -The probe state, originally returned by `probe_init/3` and subsequently +The probe state, originally returned by `Mod:probe_init/3` and subsequently modified by other probe implementation calls. This function shall return `{ok, NewState}` where `NewState` is @@ -206,7 +206,7 @@ the modified probe state that incorporates the new options. #### probe_update/2 #### -The `probe_update/2` function is invoked as follows: +The `Mod:probe_update/2` function is invoked as follows: ```erlang @@ -221,31 +221,31 @@ The arguments are as follows: The value to integrate. + `State` -The probe state, originally returned by `probe_init/3` and subsequentially +The probe state, originally returned by `Mod:probe_init/3` and subsequentially modified by other probe implementation calls. -This function can be called outside the periodic `probe_sample/1/` +This function can be called outside the periodic `Mod:probe_sample/1/` call to have the probe process a value given in `Value`. -The `probe_update/2` implementation is invoked by `exometer:update/2`, which +The `Mod:probe_update/2` implementation is invoked by `exometer:update/2`, which calls `exometer_probe:update/4`, which invokes the probe implementation. -Once processed, `probe_update/2` shall return `{ok, NewState}`, +Once processed, `Mod:probe_update/2` shall return `{ok, NewState}`, where `NewState` contains the new probe state with the processed value. #### probe_get_value/2 #### -The `probe_get_value/2` function is invoked as follows: +The `Mod:probe_get_value/2` function is invoked as follows: ```erlang probe_get_value(DataPoints, State) ``` -The `probe_get_value/2` implementation shall retrieve the value of +The `Mod:probe_get_value/2` implementation shall retrieve the value of one or more data points from the probe. The arguments are as follows: @@ -254,17 +254,17 @@ The arguments are as follows: List of data point atoms to retrieve values for. + `State` -The probe state, originally returned by `probe_init/3` and subsequentially +The probe state, originally returned by `Mod:probe_init/3` and subsequentially modified by other probe implementation calls. -The `probe_get_value/2` implementation is invoked by +The `Mod:probe_get_value/2` implementation is invoked by `exometer:get_value/2`, which calls `exometer_probe:get_value/4`, which invokes the probe implementation. If `exometer:get_value/2` is invoked with `default` as a single -data point, the probe's `probe_get_datapoints/1` function will be +data point, the probe's `Mod:probe_get_datapoints/1` function will be called to retrieve all data points supported by the probe -implementation. `probe_get_value/2` will then be called with the +implementation. `Mod:probe_get_value/2` will then be called with the returned set of data points provided as an argument. This function shall return the value of all data points provided in @@ -292,127 +292,127 @@ by the probe, the returned list shall look like below: [{ min, 0.1265 }, { max, 3338.21 }, { xyzzy, { error, unsupported } ] ``` -The `probe_get_value/2` implementation shall return `{ok, List}`, +The `Mod:probe_get_value/2` implementation shall return `{ok, List}`, where `List` is the list of data points and their values described above. No new state is returned by this function. #### probe_get_datapoints/1 #### -The `probe_get_datapoints/1` function is invoked as follows: +The `Mod:probe_get_datapoints/1` function is invoked as follows: ```erlang probe_get_datapoints(State) ``` -The `probe_get_datapoints/1` shall return a list with all data points +The `Mod:probe_get_datapoints/1` shall return a list with all data points supported by the probe The arguments are as follows: + `State` -The probe state, originally returned by `probe_init/3` and subsequentially +The probe state, originally returned by `Mod:probe_init/3` and subsequentially modified by other probe implementation calls. -The `probe_get_datapoints/1` implementation is invoked by +The `Mod:probe_get_datapoints/1` implementation is invoked by `exometer:info/2`, which calls `exometer_probe:get_datapoints/3`, which invokes the probe implementation. In cases where `exometer:get_value/2` is called with `default` as a -single data point, `probe_get_datapoints/1` is also called to +single data point, `Mod:probe_get_datapoints/1` is also called to retrieve a list of all supported data points, which is then -forwarded to `probe_get_value/2`. +forwarded to `Mod:probe_get_value/2`. -The implementation of `probe_get_datapoints/1` shall return `{ok, DpList}`, +The implementation of `Mod:probe_get_datapoints/1` shall return `{ok, DpList}`, where `DpList` is a list of data point atoms supported by the probe. #### probe_reset/1 #### -The `probe_reset/1` function is invoked as follows: +The `Mod:probe_reset/1` function is invoked as follows: ```erlang probe_reset(State) ``` -The `probe_reset/1` shall reset the state of the probe to its initial state. +The `Mod:probe_reset/1` shall reset the state of the probe to its initial state. The arguments are as follows: + `State` -The probe state, originally returned by `probe_init/3` and subsequentially +The probe state, originally returned by `Mod:probe_init/3` and subsequentially modified by other probe implementation calls. -The `probe_reset/1` implementation is invoked by +The `Mod:probe_reset/1` implementation is invoked by `exometer:reset/1`, which calls `exometer_probe:reset/3`, which invokes the probe implementation. -The implementation of `probe_reset/1` shall return `{ok, +The implementation of `Mod:probe_reset/1` shall return `{ok, NewState}`, where `NewState` contains the reset state of the probe. #### probe_sample/1 #### -The `probe_sample/1` function is invoked as follows: +The `Mod:probe_sample/1` function is invoked as follows: ```erlang probe_sample(State) ``` -The `probe_sample/1` implementation shall sample data from the +The `Mod:probe_sample/1` implementation shall sample data from the subsystem the probe is integrated with. The arguments are as follows: + `State` -The probe state, originally returned by `probe_init/3` and subsequentially +The probe state, originally returned by `Mod:probe_init/3` and subsequentially modified by other probe implementation calls. -When invoked, `probe_sample/1` is expected to interface the +When invoked, `Mod:probe_sample/1` is expected to interface the sub-system (/proc, /sysfs, etc) monitored by the probe, extract the relevant data from it, and return an updated probe state that incorporates the extracted data. -The `probe_sample/1` function is invoked by the probe thread at +The `Mod:probe_sample/1` function is invoked by the probe thread at intervals specified by the `{sample_interval, Intv}` option provided to `exometer_probe:new/3`. If this option is missing, or -set to infinity, `probe_sample/1` will never be called. +set to infinity, `Mod:probe_sample/1` will never be called. -The implementation of `probe_sample/1` shall return `{ok, +The implementation of `Mod:probe_sample/1` shall return `{ok, NewState}`, where `NewState` contains the new state of the probe with the sampled data integrated into it. #### probe_handle_msg/2 #### -The `probe_handle_msg/2` function is invoked as follows: +The `Mod:probe_handle_msg/2` function is invoked as follows: ```erlang probe_handle_msg(Msg, State) ``` -The `probe_handle_msg/1` is invoked to process messages received +The `Mod:probe_handle_msg/1` is invoked to process messages received by the probe process. The arguments are as follows: + `State` -The probe state, originally returned by `probe_init/3` and subsequentially +The probe state, originally returned by `Mod:probe_init/3` and subsequentially modified by other probe implementation calls. + `Msg` -The probe state, originally returned by `probe_init/3` and subsequentially +The probe state, originally returned by `Mod:probe_init/3` and subsequentially modified by other probe implementation calls. The implementation of this function will be called by the probe's process when it receives a message that is not recognized by the internal receive loop. -The implementation of `probe_handle_msg/2` shall return `{ok, +The implementation of `Mod:probe_handle_msg/2` shall return `{ok, NewState}`, where `NewState` contains the new state of the probe that reflects the processed message. diff --git a/doc/exometer_report.md b/doc/exometer_report.md index fae0779..263b599 100644 --- a/doc/exometer_report.md +++ b/doc/exometer_report.md @@ -42,7 +42,7 @@ will be invoked to notify the plugin of the new metrics subscription. to the recipient through a previous `exometer_report()` function. + Tear down subscription
When `exometer_report:unsubscribe()` is called, addressing the -custom report plugin, the recipient's `exometer_unsubscribe()` function +custom report plugin, the recipient's `Mod:exometer_unsubscribe/4` function will be invoked to notify the plugin of the deleted subscription. The following chapters details each of the callbacks to be implemented @@ -64,7 +64,7 @@ new plugin and return a state to be used in future plugin calls. + `Options`
Provides the prop list with attributes from the application environment for the cusom recipient. See [Configuring reporter plugins](#Configuring_reporter_plugins) for -The `exomoeter_init()` function should return `{ok, State}` where +The `Mod:exometer_init/1` function should return `{ok, State}` where State is a tuple that will be provided as a reference argument to future calls made into the plugin. Any other return formats will cancel the creation of the custom reporting plugin. @@ -72,7 +72,7 @@ cancel the creation of the custom reporting plugin. #### exometer_subscribe/5 #### -The `exometer_subscribe()` function is invoked as follows: +The `Mod:exometer_subscribe/5` function is invoked as follows: ```erlang @@ -106,7 +106,7 @@ generate an error log message by exometer. #### exometer_report/5 #### -The `exometer_report()` function is invoked as follows: +The `Mod:exometer_report/5` function is invoked as follows: ```erlang @@ -136,7 +136,7 @@ generate an error log message by exometer. #### exometer_unsubscribe/4 #### -The `exometer_unsubscribe()` function is invoked as follows: +The `Mod:exometer_unsubscribe/4` function is invoked as follows: ```erlang @@ -146,7 +146,7 @@ The `exometer_unsubscribe()` function is invoked as follows: The custom plugin can use this notification to modify and return its state in order to free resources used to maintain the now de-activated subscription. When this call returns, the given metric / data point -will not be present in future calls to `exometer_report()`. +will not be present in future calls to `exometer_report/5`. + `Metric`
Specifies the metric that is now subscribed to by the plugin as a list of atoms. @@ -161,7 +161,7 @@ can understand. + `State`
Contains the state returned by the last called plugin function. -The `exometer_unsubscribe()` function should return `{ok, State}` where +The `Mod:exometer_unsubscribe/4` function should return `{ok, State}` where State is a tuple that will be provided as a reference argument to future calls made into the plugin. Any other return formats will generate an error log message by exometer. diff --git a/doc/overview.edoc b/doc/overview.edoc index 96deb29..85a598f 100644 --- a/doc/overview.edoc +++ b/doc/overview.edoc @@ -82,8 +82,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. === Data Point === @@ -106,7 +106,7 @@ given metric. === Metric Type === 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 @@ -119,7 +119,7 @@ configurable ``exometer_entry'' callback. === Entry Callback === 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. @@ -143,7 +143,7 @@ the given subsystem and add it to the metric's data points. === Caching === -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 @@ -152,12 +152,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 @@ -174,7 +174,7 @@ 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 @@ -182,7 +182,7 @@ 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. @@ -192,10 +192,10 @@ with the Exometer Core package, as described below: === counter (exometer native) === 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'. @@ -209,10 +209,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'. @@ -220,11 +220,11 @@ entry are `value' and `ms_since_reset'. === gauge (exometer native) === 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'. @@ -232,7 +232,7 @@ are `value' and `ms_since_reset'. === exometer_histogram (probe) === 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. @@ -248,7 +248,7 @@ resource consumption. === exometer_uniform (probe) === 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 @@ -258,7 +258,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. @@ -270,7 +270,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. @@ -328,22 +328,22 @@ under the given metric. === Deleting metrics === -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. === Setting metric values === A created metric can have its value updated through the -`exometer:update()' function: +`exometer:update/2' function: 
 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 @@ -359,8 +359,8 @@ data points are available for a metric, the following call can be used: 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: 
@@ -498,7 +498,7 @@ called during upgrade, as it will re-apply the settings each time.
 
 === Configuring static subscriptions  ===
 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':
@@ -548,7 +548,7 @@ The meaning of the above tuple elements is:
 
 + `Metric :: [atoms()]'
     
Specifies the path to a metric previously created with an
-    `exometer:new()' call.
+    `exometer:new/2' call.
 
 + `DataPoint' ::  atom() | [atom()]'
     
Specifies the data point within the given metric to send to the
diff --git a/rebar.config b/rebar.config
index 94dddfe..b123182 100644
--- a/rebar.config
+++ b/rebar.config
@@ -11,14 +11,25 @@
 {ex_doc, [
           {source_url, "https://github.com/Feuerlabs/exometer_core"},
           {extras, ["README.md", "LICENSE"]},
-          {main, "readme"}]}.
+          {main, ""}]}.
 
 {profiles,
  [
   {test, [{deps, [{meck, "0.9.2"}]},
           {extra_src_dirs, [{"test", [{recursive, true}]}]}
          ]},
-  {docs, [{deps, [{edown, "0.9.1"}]}]}
+  {edown, [{deps, [{edown, "0.9.1"}]},
+           {edoc_opts,
+            [
+             {doclet, edown_doclet},
+             {app_default, "http://www.erlang.org/doc/man"},
+             {doc_path, []},
+             {branch, "master"},
+             {top_level_readme,
+              {"./README.md",
+               "https://github.com/Feuerlabs/exometer_core", "master"}}
+            ]}
+          ]}
  ]}.
 
 {erl_opts,
@@ -31,16 +42,6 @@
 
 {sub_dirs, ["src"]}.
 
-{edoc_opts,
- [
-  {doclet, edown_doclet},
-  {app_default, "http://www.erlang.org/doc/man"},
-  {doc_path, []},
-  {top_level_readme,
-   {"./README.md",
-    "https://github.com/Feuerlabs/exometer_core", "master"}}
- ]}.
-
 {xref_checks,
  [
   undefined_function_calls,
diff --git a/src/exometer_probe.erl b/src/exometer_probe.erl
index e38f9b4..8ebbaa3 100644
--- a/src/exometer_probe.erl
+++ b/src/exometer_probe.erl
@@ -41,7 +41,7 @@
 %%
 %%  Once running, the probe collects data from a subsystem, such as
 %%  `/proc', `sysfs', and `netlink', through timer-based calls to
-%%  `probe_sample/1' or explicit calls to `probe_update/2'.
+%%  `Mod:probe_sample/1' or explicit calls to `Mod:probe_update/2'.
 %%
 %%  A probe implementation can support any number of data points,
 %%  where each data point is a specifric sample from the probe. For
@@ -49,7 +49,7 @@
 %%  `rx_packets', `tx_packets', `errors', `dropped', and other data
 %%  points reported by `ifconfig(8)' and `ip(8)'.
 %%
-%%  Values are retrieved from the probe through the `probe_get_value/2'
+%%  Values are retrieved from the probe through the `Mod:probe_get_value/2'
 %%  call, which specifies the data points to be returned. The probe is
 %%  expected to gather the given data points and return them to the
 %%  caller.
@@ -61,20 +61,20 @@
 %%
 %% === behaviour/0 ===
 %%
-%% The `behaviour/0' function for an entry implementation should return
+%% The `Mod:behaviour/0' function for an entry implementation should return
 %% the atom `probe'. This function will be involved by the
 %% exometer system in order to determine if a callback is
 %% an entry or a probe.
 %%
 %% === probe_init/3 ===
-%% The `probe_init/3' function is invoked as follows:
+%% The `Mod:probe_init/3' function is invoked as follows:
 %%
 %% 
 %%      probe_init(Name, Type, Options)

 %%
 %% The implementation shall initiate the probe, create the
-%% necessary state, and return it for furure access
-%% through `probe_update/2', `probe_sample/1' and `get_value/2' calls.
+%% necessary state, and return it for future access
+%% through `Mod:probe_update/2', `Mod:probe_sample/1' and `Mod:probe_get_value/2' calls.
 %%
 %% The arguments are as follows:
 %%
@@ -90,10 +90,10 @@
 %%     Specifies an option list that contains additional setup directives to
 %%     the probe. The actual options to support are a combination of the
 %%     standard options, described below, and probe specific options
-%%     processed by `probe_init/3'.
+%%     processed by `Mod:probe_init/3'.
 %%
 %% Standard options are processed directly by `new/3', before
-%% `probe_init/3' is calledm and are as follows:
+%% `Mod:probe_init/3' is called, and are as follows:
 %%
 %% + `{priority, P}'
 %%     Will be forwarded by the probe's process to `erlang:process_flag/2'.
@@ -111,26 +111,26 @@
 %%     Specifies the interval, in milliseconds, that `exometer_probe:sample/1'.
 %%     should be invoked at.
 %%
-%% The `probe_init/3' implementation is invoked by `exometer:new/3',
+%% The `Mod:probe_init/3' implementation is invoked by `exometer:new/3',
 %% which calls `exometer_probe:new/3', which invokes the probe
 %% implementation..
 %%
-%% The `probe_init/3' function shall return `{ok, State}' where State
+%% The `Mod:probe_init/3' function shall return `{ok, State}' where State
 %% is a tuple that will be provided as a the `State' argument to all
 %% future probe implementation calls for the metric.
 %%
 %% If the `sample_interval' option has been specified in `Opts',
-%% probe_sample/2' will be invoked immediately after `probe_init/2'
-%% returns to retrieve a first sample. After that, `probe_sample/2'
+%% `Mod:probe_sample/2' will be invoked immediately after `Mod:probe_init/2'
+%% returns to retrieve a first sample. After that, `Mod:probe_sample/2'
 %% will repeatedly will be called by the probe process at the
 %% millisecond-specified interval.
 %%
-%% Should `probe_init/3' return antyhing else but `{ok, State}',
+%% Should `Mod:probe_init/3' return antyhing else but `{ok, State}',
 %% invoking `new/3' call will fail.
 %%
 %%
 %% === probe_terminate/1 ===
-%% The `probe_terminate/1' function is invoked as follows:
+%% The `Mod:probe_terminate/1' function is invoked as follows:
 %%
 %% 
 %%      probe_terminate(State)

@@ -141,29 +141,29 @@
 %% The arguments are as follows:
 %%
 %% + `State'
-%%     The probe state, originally returned by `probe_init/3' and subsequentially
+%%     The probe state, originally returned by `Mod:probe_init/3' and subsequentially
 %%     modified by other probe implementation calls.
 %%
 %%
-%% The `probe_terminate/1' implementation is invoked by `exometer:delete/1', which
+%% The `Mod:probe_terminate/1' implementation is invoked by `exometer:delete/1', which
 %% calls `exometer_probe:delete/3', which invokes the probe
 %% implementation.
 %%
 %%
 %% === probe_setopts/3 ===
-%% The `probe_setopts/2' function is invoked as follows:
+%% The `Mod:probe_setopts/2' function is invoked as follows:
 %%
 %% 
 %%      probe_setopts(Entry, Opts, State)

 %%
-%% The `probe_setopts/4' implementation is invoked by
+%% The `Mod:probe_setopts/4' implementation is invoked by
 %% `exometer:setopts/3', which calls `exometer_probe:setopts/3',
 %% which invokes the probe implementation.
 %%
 %% The implementation of this function shall modify the options of a
 %% probe. The `setopts/3' function, which will process standard
-%% options before invoking `probe_setopts/4' with the remaining
-%% options. See the documentation for `probe_init/3' for details.
+%% options before invoking `Mod:probe_setopts/4' with the remaining
+%% options. See the documentation for `Mod:probe_init/3' for details.
 %%
 %% The arguments are as follows:
 %%
@@ -178,7 +178,7 @@
 %%     The new status of the entry.
 %%
 %% + `State'
-%%     The probe state, originally returned by `probe_init/3' and subsequently
+%%     The probe state, originally returned by `Mod:probe_init/3' and subsequently
 %%     modified by other probe implementation calls.
 %%
 %% This function shall return `{ok, NewState}' where `NewState' is
@@ -186,7 +186,7 @@
 %%
 %%
 %% === probe_update/2 ===
-%% The `probe_update/2' function is invoked as follows:
+%% The `Mod:probe_update/2' function is invoked as follows:
 %%
 %% 
 %%      probe_update(Value, State)

@@ -199,28 +199,28 @@
 %%     The value to integrate.
 %%
 %% + `State'
-%%     The probe state, originally returned by `probe_init/3' and subsequentially
+%%     The probe state, originally returned by `Mod:probe_init/3' and subsequentially
 %%     modified by other probe implementation calls.
 %%
-%% This function can be called outside the periodic `probe_sample/1/'
+%% This function can be called outside the periodic `Mod:probe_sample/1/'
 %% call to have the probe process a value given in `Value'.
 %%
-%% The `probe_update/2' implementation is invoked by `exometer:update/2', which
+%% The `Mod:probe_update/2' implementation is invoked by `exometer:update/2', which
 %% calls `exometer_probe:update/4', which invokes the probe
 %% implementation.
 %%
-%% Once processed, `probe_update/2' shall return `{ok, NewState}',
+%% Once processed, `Mod:probe_update/2' shall return `{ok, NewState}',
 %% where `NewState' contains the new probe state with the processed
 %% value.
 %%
 %%
 %% === probe_get_value/2 ===
-%% The `probe_get_value/2' function is invoked as follows:
+%% The `Mod:probe_get_value/2' function is invoked as follows:
 %%
 %% 
 %%      probe_get_value(DataPoints, State)

 %%
-%% The `probe_get_value/2' implementation shall retrieve the value of
+%% The `Mod:probe_get_value/2' implementation shall retrieve the value of
 %% one or more data points from the probe.
 %%
 %% The arguments are as follows:
@@ -229,17 +229,17 @@
 %%     List of data point atoms to retrieve values for.
 %%
 %% + `State'
-%%     The probe state, originally returned by `probe_init/3' and subsequentially
+%%     The probe state, originally returned by `Mod:probe_init/3' and subsequentially
 %%     modified by other probe implementation calls.
 %%
-%% The `probe_get_value/2' implementation is invoked by
+%% The `Mod:probe_get_value/2' implementation is invoked by
 %% `exometer:get_value/2', which calls `exometer_probe:get_value/4',
 %% which invokes the probe implementation.
 %%
 %% If `exometer:get_value/2' is invoked with `default' as a single
-%% data point, the probe's `probe_get_datapoints/1' function will be
+%% data point, the probe's `Mod:probe_get_datapoints/1' function will be
 %% called to retrieve all data points supported by the probe
-%% implementation. `probe_get_value/2' will then be called with the
+%% implementation. `Mod:probe_get_value/2' will then be called with the
 %% returned set of data points provided as an argument.
 %%
 %% This function shall return the value of all data points provided in
@@ -263,116 +263,116 @@
 %% 
 %%      [{ min, 0.1265 }, { max, 3338.21 }, { xyzzy, { error, unsupported } ]

 %%
-%% The `probe_get_value/2' implementation shall return `{ok, List}',
+%% The `Mod:probe_get_value/2' implementation shall return `{ok, List}',
 %% where `List' is the list of data points and their values described
 %% above. No new state is returned by this function.
 %%
 %%
 %% === probe_get_datapoints/1 ===
-%% The `probe_get_datapoints/1' function is invoked as follows:
+%% The `Mod:probe_get_datapoints/1' function is invoked as follows:
 %%
 %% 
 %%      probe_get_datapoints(State)

 %%
-%% The `probe_get_datapoints/1' shall return a list with all data points
+%% The `Mod:probe_get_datapoints/1' shall return a list with all data points
 %% supported by the probe
 %%
 %% The arguments are as follows:
 %%
 %% + `State'
-%%     The probe state, originally returned by `probe_init/3' and subsequentially
+%%     The probe state, originally returned by `Mod:probe_init/3' and subsequentially
 %%     modified by other probe implementation calls.
 %%
-%% The `probe_get_datapoints/1' implementation is invoked by
+%% The `Mod:probe_get_datapoints/1' implementation is invoked by
 %% `exometer:info/2', which calls `exometer_probe:get_datapoints/3',
 %% which invokes the probe implementation.
 %%
 %% In cases where `exometer:get_value/2' is called with `default' as a
-%% single data point, `probe_get_datapoints/1' is also called to
+%% single data point, `Mod:probe_get_datapoints/1' is also called to
 %% retrieve a list of all supported data points, which is then
-%% forwarded to `probe_get_value/2'.
+%% forwarded to `Mod:probe_get_value/2'.
 %%
-%% The implementation of `probe_get_datapoints/1' shall return `{ok, DpList}',
+%% The implementation of `Mod:probe_get_datapoints/1' shall return `{ok, DpList}',
 %% where `DpList' is a list of data point atoms supported by the probe.
 %%
 %%
 %% === probe_reset/1 ===
-%% The `probe_reset/1' function is invoked as follows:
+%% The `Mod:probe_reset/1' function is invoked as follows:
 %%
 %% 
 %%      probe_reset(State)

 %%
-%% The `probe_reset/1' shall reset the state of the probe to its initial state.
+%% The `Mod:probe_reset/1' shall reset the state of the probe to its initial state.
 %%
 %% The arguments are as follows:
 %%
 %% + `State'
-%%     The probe state, originally returned by `probe_init/3' and subsequentially
+%%     The probe state, originally returned by `Mod:probe_init/3' and subsequentially
 %%     modified by other probe implementation calls.
 %%
 %%
-%% The `probe_reset/1' implementation is invoked by
+%% The `Mod:probe_reset/1' implementation is invoked by
 %% `exometer:reset/1', which calls `exometer_probe:reset/3', which
 %% invokes the probe implementation.
 %%
-%% The implementation of `probe_reset/1' shall return `{ok,
+%% The implementation of `Mod:probe_reset/1' shall return `{ok,
 %% NewState}', where `NewState' contains the reset state of the probe.
 %%
 %%
 %% === probe_sample/1 ===
-%% The `probe_sample/1' function is invoked as follows:
+%% The `Mod:probe_sample/1' function is invoked as follows:
 %%
 %% 
 %%      probe_sample(State)

 %%
-%% The `probe_sample/1' implementation shall sample data from the
+%% The `Mod:probe_sample/1' implementation shall sample data from the
 %% subsystem the probe is integrated with.
 %%
 %% The arguments are as follows:
 %%
 %% + `State'
-%%     The probe state, originally returned by `probe_init/3' and subsequentially
+%%     The probe state, originally returned by `Mod:probe_init/3' and subsequentially
 %%     modified by other probe implementation calls.
 %%
-%% When invoked, `probe_sample/1' is expected to interface the
+%% When invoked, `Mod:probe_sample/1' is expected to interface the
 %% sub-system (/proc, /sysfs, etc) monitored by the probe, extract the
 %% relevant data from it, and return an updated probe state that
 %% incorporates the extracted data.
 %%
-%% The `probe_sample/1' function is invoked by the probe thread at
+%% The `Mod:probe_sample/1' function is invoked by the probe thread at
 %% intervals specified by the `{sample_interval, Intv}' option
 %% provided to `exometer_probe:new/3'. If this option is missing, or
-%% set to infinity, `probe_sample/1' will never be called.
+%% set to infinity, `Mod:probe_sample/1' will never be called.
 %%
-%% The implementation of `probe_sample/1' shall return `{ok,
+%% The implementation of `Mod:probe_sample/1' shall return `{ok,
 %% NewState}', where `NewState' contains the new state of the probe
 %% with the sampled data integrated into it.
 %%
 %%
 %% === probe_handle_msg/2 ===
-%% The `probe_handle_msg/2' function is invoked as follows:
+%% The `Mod:probe_handle_msg/2' function is invoked as follows:
 %%
 %% 
 %%      probe_handle_msg(Msg, State)

 %%
-%% The `probe_handle_msg/1' is invoked to process messages received
+%% The `Mod:probe_handle_msg/1' is invoked to process messages received
 %% by the probe process.
 %%
 %% The arguments are as follows:
 %%
 %% + `State'
-%%     The probe state, originally returned by `probe_init/3' and subsequentially
+%%     The probe state, originally returned by `Mod:probe_init/3' and subsequentially
 %%     modified by other probe implementation calls.
 %%
 %% + `Msg'
-%%     The probe state, originally returned by `probe_init/3' and subsequentially
+%%     The probe state, originally returned by `Mod:probe_init/3' and subsequentially
 %%     modified by other probe implementation calls.
 %%
 %% The implementation of this function will be called by the probe's
 %% process when it receives a message that is not recognized by the
 %% internal receive loop.
 %%
-%% The implementation of `probe_handle_msg/2' shall return `{ok,
+%% The implementation of `Mod:probe_handle_msg/2' shall return `{ok,
 %% NewState}', where `NewState' contains the new state of the probe
 %% that reflects the processed message.
 %%
diff --git a/src/exometer_report.erl b/src/exometer_report.erl
index 68c9a1e..e2d2f18 100644
--- a/src/exometer_report.erl
+++ b/src/exometer_report.erl
@@ -36,7 +36,7 @@
 %%     to the recipient through a previous `exometer_report()' function.
 %%
 %% + Tear down subscription
When `exometer_report:unsubscribe()' is called, addressing the
-%%     custom report plugin, the recipient's `exometer_unsubscribe()' function
+%%     custom report plugin, the recipient's `Mod:exometer_unsubscribe/4' function
 %%     will be invoked to notify the plugin of the deleted subscription.
 %%
 %%
@@ -56,7 +56,7 @@
 %% + `Options'
Provides the prop list with attributes from the application environment
 %%     for the cusom recipient. See {@section Configuring reporter plugins} for
 %%
-%% The `exomoeter_init()' function should return `{ok, State}' where
+%% The `Mod:exometer_init/1' function should return `{ok, State}' where
 %% State is a tuple that will be provided as a reference argument to
 %% future calls made into the plugin. Any other return formats will
 %% cancel the creation of the custom reporting plugin.
@@ -64,7 +64,7 @@
 %%
 %% === exometer_subscribe/5 ===
 %%
-%% The `exometer_subscribe()' function is invoked as follows:
+%% The `Mod:exometer_subscribe/5' function is invoked as follows:
 %%
 %% 
 %%      exometer_subscribe(Metric, DataPoint, Interval, Extra, State)

@@ -96,7 +96,7 @@
 %%
 %% === exometer_report/5 ===
 %%
-%% The `exometer_report()' function is invoked as follows:
+%% The `Mod:exometer_report/5' function is invoked as follows:
 %%
 %% 
 %%      exometer_report(Metric, DataPoint, Extra, Value, State)

@@ -124,7 +124,7 @@
 %%
 %% === exometer_unsubscribe/4 ===
 %%
-%% The `exometer_unsubscribe()' function is invoked as follows:
+%% The `Mod:exometer_unsubscribe/4' function is invoked as follows:
 %%
 %% 
 %%      exometer_unsubscribe(Metric, DataPoint, Extra, State)

@@ -132,7 +132,7 @@
 %% The custom plugin can use this notification to modify and return its
 %% state in order to free resources used to maintain the now de-activated
 %% subscription. When this call returns, the given metric / data point
-%% will not be present in future calls to `exometer_report()'.
+%% will not be present in future calls to `exometer_report/5'.
 %%
 %% + `Metric'
Specifies the metric that is now subscribed to by the plugin
 %%     as a list of atoms.
@@ -147,7 +147,7 @@
 %%
 %% + `State'
Contains the state returned by the last called plugin function.
 %%
-%% The `exometer_unsubscribe()' function should return `{ok, State}' where
+%% The `Mod:exometer_unsubscribe/4' function should return `{ok, State}' where
 %% State is a tuple that will be provided as a reference argument to
 %% future calls made into the plugin. Any other return formats will
 %% generate an error log message by exometer.
@@ -653,12 +653,16 @@ new_entry(Entry) ->
 %% @doc
 %% Initializes the server
 %%
-%% @spec init(Args) -> {ok, State} |
-%%                     {ok, State, Timeout} |
-%%                     ignore |
-%%                     {stop, Reason}
 %% @end
 %%--------------------------------------------------------------------
+-spec init(Args) -> {ok, State}
+                  | {ok, State, Timeout}
+                  | ignore
+                  | {stop, Reason}
+              when Args    :: list(),
+                   State   :: any(),
+                   Timeout :: non_neg_integer() | infinity,
+                   Reason  :: any().
 init([]) ->
     process_flag(trap_exit, true),
     D = ets:foldl(
@@ -827,15 +831,9 @@ merge_env(Tag, L, E) ->
 %% @doc
 %% Handling call messages
 %%
-%% @spec handle_call(Request, From, State) ->
-%%                                   {reply, Reply, State} |
-%%                                   {reply, Reply, State, Timeout} |
-%%                                   {noreply, State} |
-%%                                   {noreply, State, Timeout} |
-%%                                   {stop, Reason, Reply, State} |
-%%                                   {stop, Reason, State}
 %% @end
 %%--------------------------------------------------------------------
+
 handle_call(start_reporters, _From, S) ->
     {reply, ok, do_start_reporters(S)};
 handle_call({subscribe,
@@ -1043,12 +1041,6 @@ handle_call(_Request, _From, State) ->
 
 %%--------------------------------------------------------------------
 %% @private
-%% @doc Handling cast messages.
-%%
-%% @spec handle_cast(Msg, State) -> {noreply, State} |
-%%                                  {noreply, State, Timeout} |
-%%                                  {stop, Reason, State}
-%% @end
 %%--------------------------------------------------------------------
 handle_cast({new_entry, Entry}, #st{} = St) ->
     [try erlang:send(Pid, {exometer_newentry, Entry})
@@ -1081,12 +1073,6 @@ handle_cast(_Msg, State) ->
 
 %%--------------------------------------------------------------------
 %% @private
-%% @doc Handling all non call/cast messages.
-%%
-%% @spec handle_info(Info, State) -> {noreply, State} |
-%%                                   {noreply, State, Timeout} |
-%%                                   {stop, Reason, State}
-%% @end
 %%--------------------------------------------------------------------
 handle_info({start_interval, Reporter, Name}, #st{} = St) ->
     case ets:lookup(?EXOMETER_REPORTERS, Reporter) of
@@ -1329,14 +1315,6 @@ cancel_timer(TRef) ->
 
 %%--------------------------------------------------------------------
 %% @private
-%% @doc
-%% This function is called by a gen_server when it is about to
-%% terminate. It should be the opposite of Reporter:init/1 and do any
-%% necessary cleaning up. When it returns, the gen_server terminates
-%% with Reason. The return value is ignored.
-%%
-%% @spec terminate(Reason, State) -> void()
-%% @end
 %%--------------------------------------------------------------------
 terminate(_Reason, _) ->
     [terminate_reporter(R) || R <- ets:tab2list(?EXOMETER_REPORTERS)],
@@ -1344,11 +1322,6 @@ terminate(_Reason, _) ->
 
 %%--------------------------------------------------------------------
 %% @private
-%% @doc
-%% Convert process state when code is changed
-%%
-%% @spec code_change(OldVsn, State, Extra) -> {ok, NewState}
-%% @end
 %%--------------------------------------------------------------------
 
 %% -record(reporter, {