dnsdist: add docs for new arguments for custom metric functions

diff --git a/pdns/dnsdistdist/docs/reference/custommetrics.rst b/pdns/dnsdistdist/docs/reference/custommetrics.rst
index b2f5b517be3d2e2b787e60e371609fbb87fbfd63..1cda8f2329dcf725d2287d8db8609009d7e6fa25 100644 (file)
--- a/pdns/dnsdistdist/docs/reference/custommetrics.rst
+++ b/pdns/dnsdistdist/docs/reference/custommetrics.rst
@@ -10,13 +10,19 @@ Then you can update those at runtime using the following functions, depending on
  * manipulate counters using :func:`incMetric` and  :func:`decMetric`
  * update a gauge using :func:`setMetric`
 
-.. function:: declareMetric(name, type, description [, prometheusName]) -> bool
+.. function:: declareMetric(name, type, description [, prometheusName|options]) -> bool
 
   .. versionadded:: 1.8.0
 
   .. versionchanged:: 1.8.1
     This function can now be used at runtime, instead of only at configuration time.
 
+  .. versionchanged:: ?
+    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.
 
@@ -25,51 +31,103 @@ Then you can update those at runtime using the following functions, depending on
   :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 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:
 
-.. function:: incMetric(name [, step]) -> int
+  * ``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.
+
+.. function:: incMetric(name [, step|options]) -> int
 
   .. versionadded:: 1.8.0
 
   .. versionchanged:: 1.8.1
     Optional ``step`` parameter added.
 
+  .. versionchanged:: ?
+    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 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 ow 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.
 
-.. function:: decMetric(name) -> int
+.. function:: decMetric(name [, step|options]) -> int
 
   .. versionadded:: 1.8.0
 
   .. versionchanged:: 1.8.1
     Optional ``step`` parameter added.
 
+  .. versionchanged:: ?
+    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.
 
-.. function:: getMetric(name) -> double
+  Options:
+
+  * ``step``: int - By ow 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.
+
+.. function:: getMetric(name [, options]) -> double
 
   .. versionadded:: 1.8.0
 
+  .. versionchanged:: ?
+    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:
 
-.. function:: setMetric(name, value) -> double
+  * ``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.
+
+.. function:: setMetric(name, value [, options]) -> double
 
   .. versionadded:: 1.8.0
 
+  .. versionchanged:: ?
+    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.