3 Usage

Add the following line at the beginning of your filter script:

require 'openmetrics'

This will cause module to be loaded and initialized. During initialization, the module will parse the configuration file, if it exists, create the metric database or open an existing one, and set up HTTP server thread for answering metric queries. If any of these actions fails, the module signals a e_failure exception.

Settings from the configuration file mfmod_openmetrics.conf, if it exists in the system configuration directory, override default module settings. See Configuration, for a detailed discussion.

The metric database file is a GNU dbm file that keeps current metric values. It can be temporary, i.e. created each time mailfromd starts up and destroyed when it terminates, or persistent, so that the data persist across program restarts. See database configuration, for details.

By default HTTP server thread listens on IP address 127.0.0.1 (localhost), port 8080. These settings can also be changed in the configuration.

After loading the module, declare metric family names you are going to use in your script. A metric family is defined using the following function:

openmetrics_declare(string name, number type, string help)

The name parameter gives the metric family name.

The type parameter declares the type of the metric. It can be one of the following: openmetrics_counter, openmetrics_gauge, or openmetrics_duration. The first two are floating-point counters. The main difference between them is that openmetrics_counter can only increase, while openmetrics_gauge can both increase and decrease. The openmetrics_duration type is a special case of openmetrics_gauge that represents the number of seconds elapsed since the counter was created or reset.

The help parameter supplies the help text.

The best place for declaring your metric families is in the startup handler, e.g.:

prog startup
do
  openmetrics_declare("accept", openmetrics_counter, "Mails accepted")
  openmetrics_declare("reject", openmetrics_counter, "Mails rejected")
  openmetrics_declare("tempfail", openmetrics_counter, "Mails tempfailed")
done

If the supplied metric family already exists, its type and help text are checked against openmetrics_declare arguments. If types does not match, the e_inval exception is signaled. Otherwise, if types match but help texts don’t, the help text is updated. Actual values of the metrics in the family are not changed.

Once the metric family is declared, you can manipulate the metrics in it using the following functions:

func openmetrics_add(string name, string labelset, number delta)
func openmetrics_incr(string name; string labelset)
func openmetrics_reset(string name; string labelset)
func openmetrics_set(string name, string labelset, number value)

Each of them identifies the metric to operate upon by its first two arguments: name, which gives the metric family name, and labelset, which supplies the label set to qualify the metric name (the latter parameter is optional if these are the only arguments the function takes). For the purposes of mfmod_openmetrics, a label set is a comma-delimited list of labels, which take form of ‘key=value’ pairs. If label set is empty, metric name is same as the metric family name. Otherwise, metric name is ‘name{labelset}’. E.g. the following call increases the value of the (counter) metric ‘action_total’:

openmetrics_incr("action_total")

Now consider the following call:

openmetrics_incr("action_total", 'action="reject"')

It is passed a non-empty label set as its second argument and therefore increases the value of the metric ‘action_total{action="reject"}’.

These functions are described in detail in chapter Functions.

Finally, add calls to the appropriate functions in the right places of your filter script. For example, to keep track of the number of accept, reject, and tempfail actions run, use openmetrics_incr before these actions, e.g.:

openmetrics_incr("reject")
reject 550 5.1.0 "Sender validity not confirmed"

Now, restart mailfromd and check if the metrics are returned by the HTTP endpoint:

curl -v http://127.0.0.1:8080/metric