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

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.

Parameters:

  • name (str) – The name of the metric, lowercase alphanumerical characters and dashes (-) only

  • type (str) – The desired type in gauge or counter

  • description (str) – The description of the metric

  • prometheusName (str) – The name to use in the prometheus metrics, if supplied. Otherwise, the regular name will be used, prefixed with dnsdist_ and - replaced by _

  • options (table) – 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

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.

Parameters:

  • name (str) – The name of the metric

  • step (int) – By how much the counter should be incremented, default to 1

  • options (table) – 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

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.

Parameters:

  • name (str) – The name of the metric

  • step (int) – By how much the counter should be decremented, default to 1.

  • options (table) – 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

Note

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

Get metric value.

Parameters:

  • name (str) – The name of the metric

  • options (table) – 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

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.

Parameters:

  • name (str) – The name of the metric

  • value (double) – The new value

  • options (table) – 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.