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]) → 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.

Return 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
  • name – 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 _.
incMetric(name[, step]) → int

New in version 1.8.0.

Changed in version 1.8.1: Optional step parameter added.

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

Parameters:
  • name (str) – The name of the metric
  • step (int) – By how much the counter should be incremented, default to 1.
decMetric(name) → int

New in version 1.8.0.

Changed in version 1.8.1: Optional step parameter added.

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

Parameters:
  • name (str) – The name of the metric
  • step (int) – By how much the counter should be decremented, default to 1.
getMetric(name) → double

New in version 1.8.0.

Get metric value

Parameters:name (str) – The name of the metric
setMetric(name, value) → double

New in version 1.8.0.

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