4 Functions

function: openmetrics_declare (string name, number type, string help, ...)

Declares the metric name with the given type and help text.

Allowed values for type are:

type: openmetrics_counter

Counter value. Metrics of this type can only increase over time.

type: openmetrics_gauge

Counter value that can both increase and decrease.

type: openmetrics_duration

Special case of openmetrics_gauge that represents the number of seconds elapsed since the counter was created or reset. This is useful for reporting uptime and similar values.

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

Any number of optional arguments can be given. They specify the LabelSets to initialize when creating the metric. To illustrate their effect, consider the following two statements:

openmetrics_declare("age", openmetrics_duration,
                    "Seconds since the database was created")
openmetrics_declare("uptime", openmetrics_duration,
                    "Mailfromd instance uptime", "")

When metric database is created, the ‘age’ metric is created without any actual instances of the metric. Until you create one with openmetrics_set, openmetrics_reset or similar function, you won’t see this metric in responses from the ‘/metric’ endpoint.

In the contrast, the declaration of ‘uptime’ creates the formal description of the metric, and defines a single instance with an empty label set. You will see the ‘uptime’ variable in the responses right after creating the database.

The openmetrics_declare function can raise the following exceptions:

e_inval

Bad number of arguments, or argument types, or bad metric type given.

e_failure

Failed to create temporary database file.

e_dbfailure

GDBM error.

function: openmetrics_incr (string name; string labelset)

Increment the value of the metric name by one. Optional labelset argument supplies a comma-separated list of ‘name=value’ parameters (labels) that qualify the counter name. If it is given, the actual metric name is ‘name{labelset}’.

This function can raise the following exceptions:

e_inval

Bad number or types of arguments.

e_failure

Failed to create temporary database file.

e_dbfailure

GDBM error. Most often this occurs because the database is locked by another process. See database-retry and database-wait in Configuration.

e_not_found

Metric not declared. This means the appropriate openmetrics_declare call is missing from prog startup.

function: openmetrics_add (string name, string labelset, number delta)

Updates the value of the metric ‘name{labelset}’ (counter or gauge) by adding delta to it.

This function can raise the same exceptions as openmetrics_incr.

function: openmetrics_reset (string name; string labelset)

Resets the metric name (or ‘name{labelset}’, if labelset is given) to its original value, i.e. 0, for openmetrics_counter and openmetrics_gauge types, and the current system local time (seconds since Epoch), for openmetrics_duration.

This function can raise the same exceptions as openmetrics_incr.

function: openmetrics_set (string name, string labelset, number value; number ifnew)

Sets the ‘name{labelset}’ metric to the given value.

If ifnew is not null, the value will be set only unless it already exits.

This function can raise the same exceptions as openmetrics_incr.

function: string openmetrics_http_address()

Returns network address the module is listening on for HTTP requests. The return value is formatted as ‘ip:port’.