From: Ensar Sarajčić Date: Mon, 16 Dec 2024 10:31:01 +0000 (+0100) Subject: dnsdist: add docs for new arguments for custom metric functions X-Git-Tag: dnsdist-2.0.0-alpha0^2~4 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=15bee38419a91c4247c3c46e083e7b3966e847fc;p=thirdparty%2Fpdns.git 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 b2f5b517be..1cda8f2329 100644 --- 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.