Custom Metrics

You can define your own metrics that can be updated using Lua.

The first step is to declare a new metric using declareMetric(). In 1.8.0 the declaration had to be done at configuration time, but since 1.8.1 it can be done at any point.

Then you can update those at runtime using the following functions, depending on the metric type:

declareMetric(name, type, description[, prometheusName|options]) → bool

New in version 1.8.0.

Changed in version 1.8.1: This function can now be used at runtime, instead of only at configuration time.

Changed in version 2.0.0: This function now takes options, with withLabels option added. prometheusName can now be provided in options.

Note

Labels are only available for prometheus. Metrics with labels are otherwise ignored.

Re-declaring an existing metric with the same name and type will not reset it. Re-declaring with the same name but a different type will cause one of them to be masked.

Returns true if declaration was successful.

param str name:The name of the metric, lowercase alphanumerical characters and dashes (-) only
param str type:The desired type in gauge or counter
param str description:
 The description of the metric
param str prometheusName:
 The name to use in the prometheus metrics, if supplied. Otherwise the regular name will be used, prefixed with dnsdist_ and - replaced by _
param table options:
 A table with key: value pairs with metric options.

Options:

  • name: str - The name to use in the prometheus metrics, if supplied. Otherwise the regular name will be used, prefixed with dnsdist_ and - replaced by _
  • withLabels=false: bool - If set to true, labels will be expected when updating this metric and it will not be automatically created without labels. Defaults to false, which automatically creates this metric without labels with default value.
incMetric(name[, step|options]) → int

New in version 1.8.0.

Changed in version 1.8.1: Optional step parameter added.

Changed in version 2.0.0: This function now takes options, with labels option added. step can now be provided in options.

Note

Labels are only available for prometheus. Metrics with labels are otherwise ignored.

Increment counter by one (or more, see the step parameter), will issue an error if the metric is not declared or not a counter.

Returns the new value.

param str name:The name of the metric
param int step:By how much the counter should be incremented, default to 1
param table options:
 A table with key: value pairs with metric options.

Options:

  • step: int - By how much the counter should be incremented, default to 1
  • labels={}: table - Set of key: value pairs with labels and their values that should be used to increment the metric. Different combinations of labels have different metric values.
decMetric(name[, step|options]) → int

New in version 1.8.0.

Changed in version 1.8.1: Optional step parameter added.

Changed in version 2.0.0: This function now takes options, with labels option added. step can now be provided in options.

Note

Labels are only available for prometheus. Metrics with labels are otherwise ignored.

Decrement counter by one (or more, see the step parameter), will issue an error if the metric is not declared or not a counter.

Returns the new value.

param str name:The name of the metric
param int step:By how much the counter should be decremented, default to 1.
param table options:
 A table with key: value pairs with metric options.

Options:

  • step: int - By how much the counter should be decremented, default to 1
  • labels={}: table - Set of key: value pairs with labels and their values that should be used to decrement the metric. Different combinations of labels have different metric values.
getMetric(name[, options]) → double

New in version 1.8.0.

Changed in version 2.0.0: This function now takes options, with labels option added.

Note

Labels are only available for prometheus. Metrics with labels are otherwise ignored.

Get metric value.

param str name:The name of the metric
param table options:
 A table with key: value pairs with metric options.

Options:

  • labels={}: table - Set of key: value pairs with labels and their values that should be used to read the metric. Different combinations of labels have different metric values.
setMetric(name, value[, options]) → double

New in version 1.8.0.

Changed in version 2.0.0: This function now takes options, with labels option added.

Note

Labels are only available for prometheus. Metrics with labels are otherwise ignored.

Set the new value, will issue an error if the metric is not declared or not a gauge.

Return the new value.

param str name:The name of the metric
param double value:
 The new value
param table options:
 A table with key: value pairs with metric options.

Options:

  • labels={}: table - Set of key: value pairs with labels and their values that should be used to set the metric. Different combinations of labels have different metric values.