From 0545944ac6aea3090a443273d0fa907e344be0dc Mon Sep 17 00:00:00 2001 From: Igor Zolotarev Date: Fri, 24 Sep 2021 14:37:42 +0300 Subject: [PATCH 1/9] Add some docs --- doc/monitoring/api_reference.rst | 61 ++++++++++++++++++++++++++++++ doc/monitoring/getting_started.rst | 55 ++++++++++++++++++++++++--- 2 files changed, 110 insertions(+), 6 deletions(-) diff --git a/doc/monitoring/api_reference.rst b/doc/monitoring/api_reference.rst index 7d0174d3..8672419c 100644 --- a/doc/monitoring/api_reference.rst +++ b/doc/monitoring/api_reference.rst @@ -343,10 +343,42 @@ Metrics functions some global label, the method argument value will be used. Note that both labels names and values in label_pairs are treated as strings. + .. function:: collect() Collect observations from each collector. +.. class:: registry + + .. method:: unregister(collector) + + Removes collector from registry + + :param table collector: collector that has to be removed + + Example: + + .. code-block:: lua + local collector = metrics.gauge('some-gauge') + + -- after some time we don't need it anymore + + metrics.registry:unregister(collector) + + .. method:: find(kind, name) + + Finds collector in registry + + :param string kind: collector kind ('counter', 'gauge', 'histogram' or 'summary') + :param string name: collector name + + Example: + + .. code-block:: lua + local collector = metrics.gauge('some-gauge') + + collector = metrics.registry:find('gauge', 'some-gauge') + .. function:: register_callback(callback) Registers a function ``callback`` which will be called right before metrics @@ -356,6 +388,15 @@ Metrics functions Most common usage is for gauge metrics updates. + Example: + + .. code-block:: lua + + metrics.register_callback(function() + local cpu_metrics = require('metrics.psutils.cpu') + cpu_metrics.update() + end) + .. function:: unregister_callback(callback) Unregisters a function ``callback`` which will be called right before metrics @@ -365,6 +406,26 @@ Metrics functions Most common usage is for unregister enabled callbacks. + Example: + + .. code-block:: lua + + local cpu_callback = function() + local cpu_metrics = require('metrics.psutils.cpu') + cpu_metrics.update() + end + + metrics.register_callback(cpu_callback) + + -- after some time we dont need that callback anymore + + metrics.unregister_callback(cpu_callback) + +.. function: invoke_callbacks() + + Invokes all registered callbacks. Needs to be called before each export. + If youre using one of default exporters, invoke_callbacks function will be called by exporter + .. _metrics-role-functions: ------------------------------------------------------------------------------- diff --git a/doc/monitoring/getting_started.rst b/doc/monitoring/getting_started.rst index 594d7027..b436bc8f 100644 --- a/doc/monitoring/getting_started.rst +++ b/doc/monitoring/getting_started.rst @@ -35,12 +35,6 @@ Enable default Tarantool metrics such as network, memory, operations, etc: metrics.enable_default_metrics() -If you use Cartridge, enable Cartridge metrics: - -.. code-block:: lua - - metrics.enable_cartridge_metrics() - Initialize the Prometheus Exporter, or export metrics in any other format: .. code-block:: lua @@ -63,6 +57,55 @@ Now you can use the HTTP API endpoint ``/metrics`` to collect your metrics in the Prometheus format. If you need your custom metrics, see the :ref:`API reference `. +.. _metrics-http +------------------------------------------------------------------------------- +Collect HTTP metrics +------------------------------------------------------------------------------- + +To enable collection of HTTP metrics, you need to create collector + +Using HTTP v1: + +.. code-block:: lua + + local httpd = require('http.server').new(ip, port) + + -- Create summary latency collector + local collector = metrics.http_middleware.build_default_collector('summary') + + -- Set route handler with summary latency collection + httpd:route({ path = '/path-1', method = 'POST' }, metrics.http_middleware.v1(handler_1, collector)) + httpd:route({ path = '/path-2', method = 'GET' }, metrics.http_middleware.v1(handler_2, collector)) + + -- Start HTTP routing + httpd:start() + +Using HTTP v2: + + +.. code-block:: lua + + local httpd = require('http.server').new(ip, port) + local router = require('http.router').new() + + router:route({ path = '/path-1', method = 'POST' }, handler_1) + router:route({ path = '/path-2', method = 'GET' }, handler_2) + + -- Create summary latency collector + local collector = metrics.http_middleware.build_default_collector('summary') + + -- Set router summary latency collection middleware + router:use(metrics.http_middleware.v2(collector), { name = 'latency_instrumentation' }) + + -- Start HTTP routing using configured router + httpd:set_router(router) + httpd:start() + +Note that you need only one collector to collect all http metrics. +If youre using default Grafana-dashboard (link) dont change collector name and description, +otherwise you wont see your metrics on charts + + .. _instance-health-check: ------------------------------------------------------------------------------- From fada649d24c99b4a6eb0105f208c36b51ad1d5eb Mon Sep 17 00:00:00 2001 From: Igor Zolotarev <63460867+yngvar-antonsson@users.noreply.github.com> Date: Tue, 5 Oct 2021 14:22:03 +0300 Subject: [PATCH 2/9] Apply suggestions from code review Co-authored-by: Georgy Moiseev --- doc/monitoring/api_reference.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/monitoring/api_reference.rst b/doc/monitoring/api_reference.rst index 8672419c..1b9349e9 100644 --- a/doc/monitoring/api_reference.rst +++ b/doc/monitoring/api_reference.rst @@ -423,7 +423,7 @@ Metrics functions .. function: invoke_callbacks() - Invokes all registered callbacks. Needs to be called before each export. + Invokes all registered callbacks. Needs to be called before each collect. If youre using one of default exporters, invoke_callbacks function will be called by exporter .. _metrics-role-functions: From 6bce8108896d9db074417b751ec91fef2ee84051 Mon Sep 17 00:00:00 2001 From: Igor Zolotarev Date: Tue, 5 Oct 2021 20:21:53 +0300 Subject: [PATCH 3/9] fixes after review --- doc/monitoring/api_reference.rst | 26 +++++++++++++++++++------- doc/monitoring/getting_started.rst | 3 +-- 2 files changed, 20 insertions(+), 9 deletions(-) diff --git a/doc/monitoring/api_reference.rst b/doc/monitoring/api_reference.rst index 1b9349e9..5329ac75 100644 --- a/doc/monitoring/api_reference.rst +++ b/doc/monitoring/api_reference.rst @@ -354,7 +354,7 @@ Metrics functions Removes collector from registry - :param table collector: collector that has to be removed + :param collector_obj collector: collector that has to be removed Example: @@ -372,6 +372,10 @@ Metrics functions :param string kind: collector kind ('counter', 'gauge', 'histogram' or 'summary') :param string name: collector name + :return: Collector object or nil + + :rtype: collector_obj + Example: .. code-block:: lua @@ -404,8 +408,6 @@ Metrics functions :param function callback: Function which takes no parameters. - Most common usage is for unregister enabled callbacks. - Example: .. code-block:: lua @@ -645,7 +647,7 @@ Using gauges: -- register a lazy gauge value update -- this will be called whenever the export is invoked in any plugins metrics.register_callback(function() - local current_cpu_usage = math.random() + local current_cpu_usage = some_cpu_collect_function() cpu_usage_gauge:set(current_cpu_usage, {app = 'tarantool'}) end) @@ -654,13 +656,18 @@ Using histograms: .. code-block:: lua local metrics = require('metrics') - + local fiber = require('fiber') -- create a histogram local http_requests_latency_hist = metrics.histogram( 'http_requests_latency', 'HTTP requests total', {2, 4, 6}) -- somewhere in the HTTP requests middleware: - local latency = math.random(1, 10) + + local t0 = fiber.clock() + observable_function() + local t1 = fiber.clock() + + local latency = t1 - t0 http_requests_latency_hist:observe(latency) Using summaries: @@ -668,6 +675,7 @@ Using summaries: .. code-block:: lua local metrics = require('metrics') + local fiber = require('fiber') -- create a summary with a window of 5 age buckets and 60s bucket lifetime local http_requests_latency = metrics.summary( @@ -677,5 +685,9 @@ Using summaries: ) -- somewhere in the HTTP requests middleware: - local latency = math.random(1, 10) + local t0 = fiber.clock() + observable_function() + local t1 = fiber.clock() + + local latency = t1 - t0 http_requests_latency:observe(latency) diff --git a/doc/monitoring/getting_started.rst b/doc/monitoring/getting_started.rst index b436bc8f..4c119586 100644 --- a/doc/monitoring/getting_started.rst +++ b/doc/monitoring/getting_started.rst @@ -82,7 +82,6 @@ Using HTTP v1: Using HTTP v2: - .. code-block:: lua local httpd = require('http.server').new(ip, port) @@ -102,7 +101,7 @@ Using HTTP v2: httpd:start() Note that you need only one collector to collect all http metrics. -If youre using default Grafana-dashboard (link) dont change collector name and description, +If youre using default Grafana-dashboard (link) dont change collector name, otherwise you wont see your metrics on charts From 97211de00951b76a3920d9fc6ffa076604d2f2b7 Mon Sep 17 00:00:00 2001 From: patiencedaur Date: Mon, 11 Oct 2021 16:17:33 +0300 Subject: [PATCH 4/9] Bring formatting in accordance with the style guide --- doc/monitoring/api_reference.rst | 150 ++++++------ doc/monitoring/getting_started.rst | 329 +++++++++++++-------------- doc/monitoring/index.rst | 21 +- doc/monitoring/metrics_reference.rst | 300 ++++++++++++------------ doc/monitoring/plugins.rst | 129 +++++------ 5 files changed, 453 insertions(+), 476 deletions(-) diff --git a/doc/monitoring/api_reference.rst b/doc/monitoring/api_reference.rst index 5329ac75..c01e8141 100644 --- a/doc/monitoring/api_reference.rst +++ b/doc/monitoring/api_reference.rst @@ -1,32 +1,28 @@ -.. _metrics-api-reference: +.. _metrics-api-reference: -=============================================================================== API reference -=============================================================================== +============= .. _collectors: -------------------------------------------------------------------------------- Collectors -------------------------------------------------------------------------------- +---------- An application using the ``metrics`` module has 4 primitives (called "collectors") at its disposal: -* :ref:`Counter ` -* :ref:`Gauge ` -* :ref:`Histogram ` -* :ref:`Summary ` +.. contents:: + :local: + :depth: 1 A collector represents one or more observations that are changing over time. .. module:: metrics -.. _counter: +.. _counter: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Counter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +counter +~~~~~~~ .. function:: counter(name [, help]) @@ -37,9 +33,9 @@ Counter :return: Counter object :rtype: counter_obj -.. class:: counter_obj +.. class:: counter_obj - .. method:: inc(num, label_pairs) + .. method:: inc(num, label_pairs) Increments an observation under ``label_pairs``. If ``label_pairs`` didn't exist before, this creates it. @@ -50,9 +46,9 @@ Counter labels names and values in label_pairs are treated as strings. - .. _counter-collect: + .. _counter-collect: - .. method:: collect() + .. method:: collect() :return: Array of ``observation`` objects for the given counter. @@ -67,11 +63,11 @@ Counter :rtype: table - .. method:: remove(label_pairs) + .. method:: remove(label_pairs) Removes an observation with ``label_pairs``. - .. method:: reset(label_pairs) + .. method:: reset(label_pairs) Set an observation under ``label_pairs`` to 0. @@ -82,9 +78,8 @@ Counter .. _gauge: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Gauge -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +gauge +~~~~~ .. function:: gauge(name [, help]) @@ -121,11 +116,10 @@ Gauge Same as Counter ``remove()``. -.. _histogram: +.. _histogram: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Histogram -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +histogram +~~~~~~~~~ .. function:: histogram(name [, help, buckets]) @@ -141,17 +135,17 @@ Histogram :rtype: histogram_obj - .. NOTE:: + .. note:: The histogram is just a set of collectors: - * ``name .. "_sum"`` - A counter holding the sum of added observations. - Contains only an empty label set. - * ``name .. "_count"`` - A counter holding the number of added observations. - Contains only an empty label set. - * ``name .. "_bucket"`` - A counter holding all bucket sizes under the label - ``le`` (low or equal). So to access a specific bucket ``x`` (``x`` is a number), - you should specify the value ``x`` for the label ``le``. + * ``name .. "_sum"`` - A counter holding the sum of added observations. + Contains only an empty label set. + * ``name .. "_count"`` - A counter holding the number of added observations. + Contains only an empty label set. + * ``name .. "_bucket"`` - A counter holding all bucket sizes under the label + ``le`` (low or equal). So to access a specific bucket ``x`` (``x`` is a number), + you should specify the value ``x`` for the label ``le``. .. class:: histogram_obj @@ -169,7 +163,7 @@ Histogram labels names and values in label_pairs are treated as strings. - .. method:: collect() + .. method:: collect() Returns a concatenation of ``counter_obj:collect()`` across all internal counters of ``histogram_obj``. For ``observation`` description, @@ -180,11 +174,10 @@ Histogram Same as Counter ``remove()``. -.. _summary: +.. _summary: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Summary -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +summary +~~~~~~~ .. function:: summary(name [, help, objectives]) @@ -222,15 +215,15 @@ Summary :rtype: summary_obj - .. NOTE:: + .. note:: The summary is just a set of collectors: - * ``name .. "_sum"`` - A counter holding the sum of added observations. - * ``name .. "_count"`` - A counter holding the number of added observations. - * ``name`` - It's holding all quantiles under observation under the label - ``quantile`` (low or equal). So to access a specific quantile ``x`` (``x`` is a number), - you should specify the value ``x`` for the label ``quantile``. + * ``name .. "_sum"`` - A counter holding the sum of added observations. + * ``name .. "_count"`` - A counter holding the number of added observations. + * ``name`` - It's holding all quantiles under observation under the label + ``quantile`` (low or equal). So to access a specific quantile ``x`` + (``x`` is a number), you should specify the value ``x`` for the label ``quantile``. .. class:: summary_obj @@ -263,11 +256,10 @@ Summary Same as Counter ``remove()``. -.. _labels: +.. _labels: -------------------------------------------------------------------------------- Labels -------------------------------------------------------------------------------- +------ All collectors support providing ``label_pairs`` on data modification. Labels are basically a metainfo that you associate with a metric in the format @@ -292,11 +284,10 @@ In the example above, we could derive these time series: You can also set global labels by calling ``metrics.set_global_labels({ label = value, ...})``. -.. _metrics-functions: +.. _metrics-functions: -------------------------------------------------------------------------------- Metrics functions -------------------------------------------------------------------------------- +----------------- .. function:: enable_default_metrics([include, exclude]) @@ -308,21 +299,21 @@ Metrics functions Default metrics names: - * "network" - * "operations" - * "system" - * "replicas" - * "info" - * "slab" - * "runtime" - * "memory" - * "spaces" - * "fibers" - * "cpu" - * "vinyl" - * "luajit" - * "cartridge_issues" - * "clock" + * ``network`` + * ``operations`` + * ``system`` + * ``replicas`` + * ``info`` + * ``slab`` + * ``runtime`` + * ``memory`` + * ``spaces`` + * ``fibers`` + * ``cpu`` + * ``vinyl`` + * ``luajit`` + * ``cartridge_issues`` + * ``clock`` See :ref:`metrics reference ` for details. @@ -359,6 +350,7 @@ Metrics functions Example: .. code-block:: lua + local collector = metrics.gauge('some-gauge') -- after some time we don't need it anymore @@ -379,6 +371,7 @@ Metrics functions Example: .. code-block:: lua + local collector = metrics.gauge('some-gauge') collector = metrics.registry:find('gauge', 'some-gauge') @@ -423,16 +416,16 @@ Metrics functions metrics.unregister_callback(cpu_callback) -.. function: invoke_callbacks() +.. function:: invoke_callbacks() Invokes all registered callbacks. Needs to be called before each collect. - If youre using one of default exporters, invoke_callbacks function will be called by exporter + If youre using one of default exporters, + invoke_callbacks function will be called by exporter -.. _metrics-role-functions: +.. _metrics-role-functions: -------------------------------------------------------------------------------- Metrics role API -------------------------------------------------------------------------------- +---------------- Functions to call with ``metrics = require('cartridge.roles.metrics')`` in ``init.lua`` @@ -483,18 +476,17 @@ Functions to call with ``metrics = require('cartridge.roles.metrics')`` in ``ini are treated as strings. :param table label_pairs: Table containing label names as string keys, - label values as values (table). + label values as values (table). .. code-block:: lua local metrics = require('cartridge.roles.metrics') metrics.set_default_labels({ ['my-custom-label'] = 'label-value' }) -.. _collecting-http-statistics: +.. _collecting-http-statistics: -------------------------------------------------------------------------------- Collecting HTTP requests latency statistics -------------------------------------------------------------------------------- +------------------------------------------- ``metrics`` also provides a middleware for monitoring HTTP (set by the `http `_ module) @@ -570,11 +562,10 @@ latency statistics. For a more detailed example, see https://github.com/tarantool/metrics/blob/master/example/HTTP/latency_v2.lua -.. _cpu-usage-metrics: +.. _cpu-usage-metrics: -------------------------------------------------------------------------------- CPU usage metrics -------------------------------------------------------------------------------- +----------------- CPU metrics work only on Linux. See :ref:`metrics reference ` for details. To enable it you should register callback: @@ -613,9 +604,8 @@ for details. To enable it you should register callback: .. _example: -------------------------------------------------------------------------------- Examples -------------------------------------------------------------------------------- +-------- Below are examples of using metrics primitives. diff --git a/doc/monitoring/getting_started.rst b/doc/monitoring/getting_started.rst index 4c119586..ebca48c6 100644 --- a/doc/monitoring/getting_started.rst +++ b/doc/monitoring/getting_started.rst @@ -1,14 +1,12 @@ -.. _monitoring-getting-started: +.. _monitoring-getting-started: -================================================================================ Monitoring: getting started -================================================================================ +=========================== .. _tarantool-metrics: -------------------------------------------------------------------------------- Tarantool -------------------------------------------------------------------------------- +--------- First, you need to install the ``metrics`` package: @@ -57,16 +55,16 @@ Now you can use the HTTP API endpoint ``/metrics`` to collect your metrics in the Prometheus format. If you need your custom metrics, see the :ref:`API reference `. -.. _metrics-http -------------------------------------------------------------------------------- +.. _metrics-http: + Collect HTTP metrics -------------------------------------------------------------------------------- +-------------------- To enable collection of HTTP metrics, you need to create collector Using HTTP v1: -.. code-block:: lua +.. code-block:: lua local httpd = require('http.server').new(ip, port) @@ -82,7 +80,7 @@ Using HTTP v1: Using HTTP v2: -.. code-block:: lua +.. code-block:: lua local httpd = require('http.server').new(ip, port) local router = require('http.router').new() @@ -107,9 +105,8 @@ otherwise you wont see your metrics on charts .. _instance-health-check: -------------------------------------------------------------------------------- Instance health check -------------------------------------------------------------------------------- +--------------------- In production environments Tarantool Cluster usually has a large number of so called "routers", Tarantool instances that handle input load and it is required to evenly @@ -122,9 +119,8 @@ with a 500 status code. .. _cartridge-role: -------------------------------------------------------------------------------- Cartridge role -------------------------------------------------------------------------------- +-------------- ``cartridge.roles.metrics`` is a role for `Tarantool Cartridge `_. @@ -133,162 +129,165 @@ via configuration. **Usage** -#. Add ``metrics`` package to dependencies in the ``.rockspec`` file. - Make sure that you are using version **0.3.0** or higher. - - .. code-block:: lua - - dependencies = { - ... - 'metrics >= 0.3.0-1', - ... - } - -#. Make sure that you have ``cartridge.roles.metrics`` - in the roles list in ``cartridge.cfg`` - in your entry-point file (e.g. ``init.lua``). - - .. code-block:: lua - - local ok, err = cartridge.cfg({ - ... - roles = { - ... - 'cartridge.roles.metrics', - ... - }, - }) - -#. To view metrics via API endpoints, use ``set_export``. - - **NOTE** that ``set_export`` has lower priority than clusterwide config and could be overriden by the metrics config. - - .. code-block:: lua - - local metrics = require('cartridge.roles.metrics') - metrics.set_export({ - { - path = '/path_for_json_metrics', - format = 'json' - }, - { - path = '/path_for_prometheus_metrics', - format = 'prometheus' - }, - { - path = '/health', - format = 'health' - } - }) - - You can add several entry points of the same format by different paths, - like this: - - .. code-block:: lua - - metrics.set_export({ - { - path = '/path_for_json_metrics', - format = 'json' - }, - { - path = '/another_path_for_json_metrics', - format = 'json' - }, - }) - - The metrics will be available on the path specified in ``path`` in the format - specified in ``format``. - -#. Enable role in the interface: - - .. image:: images/role-enable.png - :align: center - - Since version **0.6.0** metrics role is permanent and enabled on instances by default. - -#. After role initialization, default metrics will be enabled and the global - label ``'alias'`` will be set. **Note** that ``'alias'`` label value is set by - instance :ref:`configuration option ` ``alias`` or ``instance_name`` (since **0.6.1**). - - If you need to use the functionality of any - metrics package, you may get it as a Cartridge service and use it like - a regular package after ``require``: - - .. code-block:: lua - - local cartridge = require('cartridge') - local metrics = cartridge.service_get('metrics') - -#. There is an ability in Tarantool Cartridge >= ``'2.4.0'`` to set a zone for each - server in cluster. If zone was set for the server ``'zone'`` label for all metrics - of this server will be added. - -#. To change metrics HTTP path in **runtime**, you may use the following configuration - (to learn more about Cartridge configuration, see - `this `_). - We don't recommend to use it to set up metrics role, use ``set_export`` instead. - - .. code-block:: yaml - - metrics: - export: - - path: '/path_for_json_metrics' - format: 'json' - - path: '/path_for_prometheus_metrics' - format: 'prometheus' - - path: '/health' - format: 'health' - - .. image:: images/role-config.png - :align: center - -#. To set custom global labels, you may use the following configuration. - - .. code-block:: yaml - - metrics: - export: - - path: '/metrics' - format: 'json' - global-labels: - my-custom-label: label-value - - **OR** use ``set_default_labels`` function in ``init.lua``. +#. Add ``metrics`` package to dependencies in the ``.rockspec`` file. + Make sure that you are using version **0.3.0** or higher. + + .. code-block:: lua + + dependencies = { + ... + 'metrics >= 0.3.0-1', + ... + } + +#. Make sure that you have ``cartridge.roles.metrics`` + in the roles list in ``cartridge.cfg`` + in your entry-point file (e.g. ``init.lua``). + + .. code-block:: lua + + local ok, err = cartridge.cfg({ + ... + roles = { + ... + 'cartridge.roles.metrics', + ... + }, + }) + +#. To view metrics via API endpoints, use ``set_export``. + + .. note:: + + ``set_export`` has lower priority than clusterwide config + and could be overriden by the metrics config. - .. code-block:: lua + .. code-block:: lua - local metrics = require('cartridge.roles.metrics') - metrics.set_default_labels({ ['my-custom-label'] = 'label-value' }) + local metrics = require('cartridge.roles.metrics') + metrics.set_export({ + { + path = '/path_for_json_metrics', + format = 'json' + }, + { + path = '/path_for_prometheus_metrics', + format = 'prometheus' + }, + { + path = '/health', + format = 'health' + } + }) -#. To choose which default metrics are exported, you may use the following configuration. + You can add several entry points of the same format by different paths, + like this: - When you add include section, only metrics from this section are exported: - - .. code-block:: yaml - - metrics: - export: - - path: '/metrics' - format: 'json' - # export only vinyl, luajit and memory metrics: - include: - - vinyl - - luajit - - memory + .. code-block:: lua + + metrics.set_export({ + { + path = '/path_for_json_metrics', + format = 'json' + }, + { + path = '/another_path_for_json_metrics', + format = 'json' + }, + }) + + The metrics will be available on the path specified in ``path`` in the format + specified in ``format``. + +#. Enable role in the interface: + + .. image:: images/role-enable.png + :align: center + + Since version **0.6.0** metrics role is permanent and enabled on instances by default. + +#. After role initialization, default metrics will be enabled and the global + label ``'alias'`` will be set. **Note** that ``'alias'`` label value is set by + instance :ref:`configuration option ` ``alias`` or ``instance_name`` (since **0.6.1**). + + If you need to use the functionality of any + metrics package, you may get it as a Cartridge service and use it like + a regular package after ``require``: + + .. code-block:: lua + + local cartridge = require('cartridge') + local metrics = cartridge.service_get('metrics') + +#. There is an ability in Tarantool Cartridge >= ``'2.4.0'`` to set a zone for each + server in cluster. If zone was set for the server ``'zone'`` label for all metrics + of this server will be added. + +#. To change metrics HTTP path in **runtime**, you may use the following configuration + (to learn more about Cartridge configuration, see + `this `_). + We don't recommend to use it to set up metrics role, use ``set_export`` instead. + + .. code-block:: yaml + + metrics: + export: + - path: '/path_for_json_metrics' + format: 'json' + - path: '/path_for_prometheus_metrics' + format: 'prometheus' + - path: '/health' + format: 'health' + + .. image:: images/role-config.png + :align: center + +#. To set custom global labels, you may use the following configuration. + + .. code-block:: yaml + + metrics: + export: + - path: '/metrics' + format: 'json' + global-labels: + my-custom-label: label-value + + **OR** use ``set_default_labels`` function in ``init.lua``. + + .. code-block:: lua + + local metrics = require('cartridge.roles.metrics') + metrics.set_default_labels({ ['my-custom-label'] = 'label-value' }) + +#. To choose which default metrics are exported, you may use the following configuration. + + When you add include section, only metrics from this section are exported: + + .. code-block:: yaml + + metrics: + export: + - path: '/metrics' + format: 'json' + # export only vinyl, luajit and memory metrics: + include: + - vinyl + - luajit + - memory - When you add exclude section, metrics from this section are removed from default metrics list: + When you add exclude section, metrics from this section are removed from default metrics list: - .. code-block:: yaml + .. code-block:: yaml - metrics: - export: - - path: '/metrics' - format: 'json' - # export all metrics except vinyl, luajit and memory: - exclude: - - vinyl - - luajit - - memory + metrics: + export: + - path: '/metrics' + format: 'json' + # export all metrics except vinyl, luajit and memory: + exclude: + - vinyl + - luajit + - memory - You can see full list of default metrics in :ref:`API reference `. + You can see full list of default metrics in :ref:`API reference `. diff --git a/doc/monitoring/index.rst b/doc/monitoring/index.rst index abd84e62..5074a79e 100644 --- a/doc/monitoring/index.rst +++ b/doc/monitoring/index.rst @@ -1,8 +1,7 @@ -.. _monitoring: +.. _monitoring: -******************************************************************************** Monitoring -******************************************************************************** +========== Monitoring is the process of measuring and tracking Tarantool performance according to key metrics influencing it. These metrics are typically monitored @@ -10,12 +9,12 @@ in real time, allowing you to identify or predict issues. This chapter includes the following sections: -.. toctree:: - :maxdepth: 2 - :numbered: 0 +.. toctree:: + :maxdepth: 2 + :numbered: 0 - getting_started - metrics_reference - api_reference - plugins - grafana_dashboard + getting_started + metrics_reference + api_reference + plugins + grafana_dashboard diff --git a/doc/monitoring/metrics_reference.rst b/doc/monitoring/metrics_reference.rst index 60ca259a..2b951300 100644 --- a/doc/monitoring/metrics_reference.rst +++ b/doc/monitoring/metrics_reference.rst @@ -1,54 +1,50 @@ -.. _metrics-reference: +.. _metrics-reference: -=============================================================================== Metrics reference -=============================================================================== +================= This page provides a detailed description of metrics from the ``metrics`` module. -------------------------------------------------------------------------------- General metrics -------------------------------------------------------------------------------- +--------------- General instance information: -* ``tnt_cfg_current_time``—instance system time in the Unix timestamp format. +* ``tnt_cfg_current_time``—instance system time in the Unix timestamp format. -* ``tnt_info_uptime``—time in seconds since instance has started. +* ``tnt_info_uptime``—time in seconds since instance has started. -* ``tnt_read_only``—is instance in read only mode (value is 1 if true and 0 if false). +* ``tnt_read_only``—is instance in read only mode (value is 1 if true and 0 if false). -.. _memory-general: +.. _memory-general: -------------------------------------------------------------------------------- Memory general -------------------------------------------------------------------------------- +-------------- These metrics provide a picture of memory usage by the Tarantool process. -* ``tnt_info_memory_cache``—number of - bytes in the cache for the tuples stored for the vinyl storage engine. +* ``tnt_info_memory_cache``—number of + bytes in the cache for the tuples stored for the vinyl storage engine. -* ``tnt_info_memory_data``—number of bytes used for storing user data (the tuples) - with the memtx engine and with level 0 of the vinyl engine, without taking memory fragmentation into account. +* ``tnt_info_memory_data``—number of bytes used for storing user data (the tuples) + with the memtx engine and with level 0 of the vinyl engine, without taking memory fragmentation into account. -* ``tnt_info_memory_index``—number of bytes used for indexing user data, - including memtx and vinyl memory tree extents, the vinyl page index, and the vinyl bloom filters. +* ``tnt_info_memory_index``—number of bytes used for indexing user data, + including memtx and vinyl memory tree extents, the vinyl page index, and the vinyl bloom filters. -* ``tnt_info_memory_lua``—number of bytes used for the Lua runtime. - Lua memory is bounded by 2 GB per instance. Monitoring this metric can prevent memory overflow. +* ``tnt_info_memory_lua``—number of bytes used for the Lua runtime. + Lua memory is bounded by 2 GB per instance. Monitoring this metric can prevent memory overflow. -* ``tnt_info_memory_net``—number of bytes used for network input/output buffers. +* ``tnt_info_memory_net``—number of bytes used for network input/output buffers. -* ``tnt_info_memory_tx``—number of bytes in use by active transactions. - For the vinyl storage engine, this is the total size of all allocated objects - (struct ``txv``, struct ``vy_tx``, struct ``vy_read_interval``) and tuples pinned for those objects. +* ``tnt_info_memory_tx``—number of bytes in use by active transactions. + For the vinyl storage engine, this is the total size of all allocated objects + (struct ``txv``, struct ``vy_tx``, struct ``vy_read_interval``) and tuples pinned for those objects. -.. _memory-allocation: +.. _memory-allocation: -------------------------------------------------------------------------------- Memory allocation -------------------------------------------------------------------------------- +----------------- Provides a memory usage report for the slab allocator. The slab allocator is the main allocator used to store tuples. @@ -58,170 +54,163 @@ To learn more about use cases, refer to the Available memory, bytes: -* ``tnt_slab_quota_size``—the amount of memory available to store tuples and indexes, equals ``memtx_memory``. +* ``tnt_slab_quota_size``—the amount of memory available to store tuples and indexes, equals ``memtx_memory``. -* ``tnt_slab_arena_size``—the total memory used for tuples and indexes together (including allocated, but currently free slabs). +* ``tnt_slab_arena_size``—the total memory used for tuples and indexes together (including allocated, but currently free slabs). -* ``tnt_slab_items_size``—the total amount of memory (including allocated, but currently free slabs) used only for tuples, no indexes. +* ``tnt_slab_items_size``—the total amount of memory (including allocated, but currently free slabs) used only for tuples, no indexes. Memory usage, bytes: -* ``tnt_slab_quota_used``—the amount of memory that is already reserved by the slab allocator. +* ``tnt_slab_quota_used``—the amount of memory that is already reserved by the slab allocator. -* ``tnt_slab_arena_used``—the efficient memory used for storing tuples and indexes together (omitting allocated, but currently free slabs). +* ``tnt_slab_arena_used``—the efficient memory used for storing tuples and indexes together (omitting allocated, but currently free slabs). -* ``tnt_slab_items_used``—the efficient amount of memory (omitting allocated, but currently free slabs) used only for tuples, no indexes. +* ``tnt_slab_items_used``—the efficient amount of memory (omitting allocated, but currently free slabs) used only for tuples, no indexes. Memory utilization, %: -* ``tnt_slab_quota_used_ratio``—tnt_slab_quota_used / tnt_slab_quota_size. +* ``tnt_slab_quota_used_ratio``—tnt_slab_quota_used / tnt_slab_quota_size. -* ``tnt_slab_arena_used_ratio``—tnt_slab_arena_used / tnt_slab_arena_used. +* ``tnt_slab_arena_used_ratio``—tnt_slab_arena_used / tnt_slab_arena_used. -* ``tnt_slab_items_used_ratio``—tnt_slab_items_used / tnt_slab_items_size. +* ``tnt_slab_items_used_ratio``—tnt_slab_items_used / tnt_slab_items_size. -.. _spaces: +.. _spaces: -------------------------------------------------------------------------------- Spaces -------------------------------------------------------------------------------- +------ These metrics provide specific information about each individual space in a Tarantool instance: -* ``tnt_space_len``—number of records in the space. - This metric always has 2 labels: ``{name="test", engine="memtx"}``, - where ``name`` is the name of the space, and - ``engine`` is the engine of the space. +* ``tnt_space_len``—number of records in the space. + This metric always has 2 labels: ``{name="test", engine="memtx"}``, + where ``name`` is the name of the space, and + ``engine`` is the engine of the space. -* ``tnt_space_bsize``—the total number of bytes in all tuples. - This metric always has 2 labels: ``{name="test", engine="memtx"}``, - where ``name`` is the name of the space, and - ``engine`` is the engine of the space. +* ``tnt_space_bsize``—the total number of bytes in all tuples. + This metric always has 2 labels: ``{name="test", engine="memtx"}``, + where ``name`` is the name of the space, and + ``engine`` is the engine of the space. -* ``tnt_space_index_bsize``—the total number of bytes taken by the index. - This metric always has 2 labels: ``{name="test", index_name="pk"}``, - where ``name`` is the name of the space, and - ``index_name`` is the name of the index. +* ``tnt_space_index_bsize``—the total number of bytes taken by the index. + This metric always has 2 labels: ``{name="test", index_name="pk"}``, + where ``name`` is the name of the space, and + ``index_name`` is the name of the index. -* ``tnt_space_total_bsize``—the total size of tuples and all indexes in space. - This metric always has 2 labels: ``{name="test", engine="memtx"}``, - where ``name`` is the name of the space, and - ``engine`` is the engine of the space. +* ``tnt_space_total_bsize``—the total size of tuples and all indexes in space. + This metric always has 2 labels: ``{name="test", engine="memtx"}``, + where ``name`` is the name of the space, and + ``engine`` is the engine of the space. -* ``tnt_space_count``—the total tuples count for vinyl. - This metric always has labels—``{name="test", engine="vinyl"}``, - where ``name`` is the name of the space, and - ``engine`` is the engine of the space. +* ``tnt_space_count``—the total tuples count for vinyl. + This metric always has labels—``{name="test", engine="vinyl"}``, + where ``name`` is the name of the space, and + ``engine`` is the engine of the space. -.. _network: +.. _network: -------------------------------------------------------------------------------- Network -------------------------------------------------------------------------------- +------- Network activity stats. This can be used to monitor network load, usage peaks and traffic drops. Sent bytes: -* ``tnt_net_sent_total``—bytes sent from this instance over network since instance start time. +* ``tnt_net_sent_total``—bytes sent from this instance over network since instance start time. Received bytes: -* ``tnt_net_received_total``—bytes this instance has received since instance start time. +* ``tnt_net_received_total``—bytes this instance has received since instance start time. Connections: -* ``tnt_net_connections_total``—number of incoming network connections since instance start time. +* ``tnt_net_connections_total``—number of incoming network connections since instance start time. -* ``tnt_net_connections_current``—number of active network connections. +* ``tnt_net_connections_current``—number of active network connections. Requests: -* ``tnt_net_requests_total``—number of network requests this instance has handled since instance start time. +* ``tnt_net_requests_total``—number of network requests this instance has handled since instance start time. -* ``tnt_net_requests_current``—amount of pending network requests. +* ``tnt_net_requests_current``—amount of pending network requests. -.. _metrics-fibers: +.. _metrics-fibers: -------------------------------------------------------------------------------- Fibers -------------------------------------------------------------------------------- +------ Provides the statistics of :ref:`fibers `. If your app creates a lot of fibers, it can be used for monitoring fibers count and memory usage: -* ``tnt_fiber_count``—number of fibers. +* ``tnt_fiber_count``—number of fibers. -* ``tnt_fiber_csw``—overall amount of fibers context switches. +* ``tnt_fiber_csw``—overall amount of fibers context switches. -* ``tnt_fiber_memalloc``—the amount of memory that is reserved for fibers. +* ``tnt_fiber_memalloc``—the amount of memory that is reserved for fibers. -* ``tnt_fiber_memused``—the amount of memory that is used by fibers. +* ``tnt_fiber_memused``—the amount of memory that is used by fibers. -.. _metrics-operations: +.. _metrics-operations: -------------------------------------------------------------------------------- Operations -------------------------------------------------------------------------------- +---------- Number of iproto requests this instance has processed, aggregated by request type. It can be used to find out which type of operation clients make more often. -* ``tnt_stats_op_total``—total number of calls since server start +* ``tnt_stats_op_total``—total number of calls since server start That metric have ``operation`` label to be able to distinguish different request types, e.g.: ``{operation="select"}`` Request type could be one of: -- ``delete``—delete calls -- ``error``—requests resulted in an error -- ``update``—update calls -- ``call``—requests to execute stored procedures -- ``auth``—authentication requests -- ``eval``—calls to evaluate lua code -- ``replace``—replace call -- ``execute``—execute SQL calls -- ``select``—select calls -- ``upsert``—upsert calls -- ``prepare``—SQL prepare calls -- ``insert``—insert calls - -.. _metrics-replication: - -------------------------------------------------------------------------------- +* ``delete``—delete calls +* ``error``—requests resulted in an error +* ``update``—update calls +* ``call``—requests to execute stored procedures +* ``auth``—authentication requests +* ``eval``—calls to evaluate lua code +* ``replace``—replace call +* ``execute``—execute SQL calls +* ``select``—select calls +* ``upsert``—upsert calls +* ``prepare``—SQL prepare calls +* ``insert``—insert calls + +.. _metrics-replication: + Replication -------------------------------------------------------------------------------- +----------- Provides information of current replication status. To learn more about replication mechanism in Tarantool, see :ref:`this `. -* ``tnt_info_lsn``—LSN of the instance. +* ``tnt_info_lsn``—LSN of the instance. -* ``tnt_info_vclock``—LSN number in vclock. This metric always has label ``{id="id"}``, - where ``id`` is the instance's number in the replicaset. +* ``tnt_info_vclock``—LSN number in vclock. This metric always has label ``{id="id"}``, + where ``id`` is the instance's number in the replicaset. -* ``tnt_replication_replica__lsn`` / ``tnt_replication_master__lsn``—LSN of master/replica, where - ``id`` is the instance's number in the replicaset. +* ``tnt_replication_replica__lsn`` / ``tnt_replication_master__lsn``—LSN of master/replica, where + ``id`` is the instance's number in the replicaset. -* ``tnt_replication__lag``—replication lag value in seconds, where - ``id`` is the instance's number in the replicaset. +* ``tnt_replication__lag``—replication lag value in seconds, where + ``id`` is the instance's number in the replicaset. -.. _metrics-runtime: +.. _metrics-runtime: -------------------------------------------------------------------------------- Runtime -------------------------------------------------------------------------------- +------- -* ``tnt_runtime_lua``—Lua garbage collector size in bytes. +* ``tnt_runtime_lua``—Lua garbage collector size in bytes. -* ``tnt_runtime_used``—number of bytes used for the Lua runtime. +* ``tnt_runtime_used``—number of bytes used for the Lua runtime. -.. _metrics-cartridge: +.. _metrics-cartridge: -------------------------------------------------------------------------------- Cartridge -------------------------------------------------------------------------------- +--------- ``tnt_cartridge_issues``—number of :ref:`issues of instance `. @@ -239,96 +228,95 @@ This metric always has the label ``{delta="..."}``, which is one of: * ``max``—the difference with the fastest clock (always positive), * ``min``—the difference with the slowest clock (always negative). -.. _metrics-luajit: -------------------------------------------------------------------------------- +.. _metrics-luajit: + LuaJIT metrics -------------------------------------------------------------------------------- +-------------- LuaJIT metrics help understand the stage of Lua garbage collector. They are available in Tarantool 2.6 and later. General JIT metrics: -* ``lj_jit_snap_restore``—overall number of snap restores. +* ``lj_jit_snap_restore``—overall number of snap restores. -* ``lj_jit_trace_num``—number of JIT traces. +* ``lj_jit_trace_num``—number of JIT traces. -* ``lj_jit_trace_abort``—overall number of abort traces. +* ``lj_jit_trace_abort``—overall number of abort traces. -* ``lj_jit_mcode_size``—total size of all allocated machine code areas. +* ``lj_jit_mcode_size``—total size of all allocated machine code areas. JIT strings: -* ``lj_strhash_hit``—number of strings being interned. +* ``lj_strhash_hit``—number of strings being interned. -* ``lj_strhash_miss``—total number of string allocations. +* ``lj_strhash_miss``—total number of string allocations. GC steps: -* ``lj_gc_steps_atomic``—count of incremental GC steps (atomic state). +* ``lj_gc_steps_atomic``—count of incremental GC steps (atomic state). -* ``lj_gc_steps_sweepstring``—count of incremental GC steps (sweepstring state). +* ``lj_gc_steps_sweepstring``—count of incremental GC steps (sweepstring state). -* ``lj_gc_steps_finalize``—count of incremental GC steps (finalize state). +* ``lj_gc_steps_finalize``—count of incremental GC steps (finalize state). -* ``lj_gc_steps_sweep``—count of incremental GC steps (sweep state). +* ``lj_gc_steps_sweep``—count of incremental GC steps (sweep state). -* ``lj_gc_steps_propagate``—count of incremental GC steps (propagate state). +* ``lj_gc_steps_propagate``—count of incremental GC steps (propagate state). -* ``lj_gc_steps_pause``—count of incremental GC steps (pause state). +* ``lj_gc_steps_pause``—count of incremental GC steps (pause state). Allocations: -* ``lj_gc_strnum``—number of allocated ``string`` objects. +* ``lj_gc_strnum``—number of allocated ``string`` objects. -* ``lj_gc_tabnum``—number of allocated ``table`` objects. +* ``lj_gc_tabnum``—number of allocated ``table`` objects. -* ``lj_gc_cdatanum``—number of allocated ``cdata`` objects. +* ``lj_gc_cdatanum``—number of allocated ``cdata`` objects. -* ``lj_gc_udatanum``—number of allocated ``udata`` objects. +* ``lj_gc_udatanum``—number of allocated ``udata`` objects. -* ``lj_gc_freed`` —total amount of freed memory. +* ``lj_gc_freed`` —total amount of freed memory. -* ``lj_gc_total``—current allocated Lua memory. +* ``lj_gc_total``—current allocated Lua memory. -* ``lj_gc_allocated``—total amount of allocated memory. +* ``lj_gc_allocated``—total amount of allocated memory. -.. _metrics-psutils: +.. _metrics-psutils: -------------------------------------------------------------------------------- CPU metrics -------------------------------------------------------------------------------- +----------- These metrics provide the CPU usage statistics. They are only available on Linux. -* ``tnt_cpu_count``—total number of processors configured by the operating system. +* ``tnt_cpu_count``—total number of processors configured by the operating system. -* ``tnt_cpu_total``—host CPU time. +* ``tnt_cpu_total``—host CPU time. -* ``tnt_cpu_thread``—Tarantool thread CPU time. This metric always has labels - ``{kind="user", thread_name="tarantool", thread_pid="pid", file_name="init.lua"}``, - where: +* ``tnt_cpu_thread``—Tarantool thread CPU time. This metric always has labels + ``{kind="user", thread_name="tarantool", thread_pid="pid", file_name="init.lua"}``, + where: - * ``kind`` can be either ``user`` or ``system``. - * ``thread_name`` is ``tarantool``, ``wal``, ``iproto``, or ``coio``. - * ``file_name`` is the entrypoint file name, for example, ``init.lua``. + - ``kind`` can be either ``user`` or ``system``. + - ``thread_name`` is ``tarantool``, ``wal``, ``iproto``, or ``coio``. + - ``file_name`` is the entrypoint file name, for example, ``init.lua``. There are also the following cross-platform metrics obtained using the call ``getrusage()`` -* ``tnt_cpu_user_time`` - Tarantool CPU user time. -* ``tnt_cpu_system_time`` - Tarantool CPU system time. +* ``tnt_cpu_user_time`` - Tarantool CPU user time. +* ``tnt_cpu_system_time`` - Tarantool CPU system time. -.. _metrics-vinyl: +.. _metrics-vinyl: -------------------------------------------------------------------------------- Vinyl -------------------------------------------------------------------------------- +----- Vinyl metrics provide the :ref:`vinyl engine ` statistics. -**Disk** +Disk +~~~~ The disk metrics are used to monitor the overall data size on disk. @@ -340,7 +328,8 @@ The disk metrics are used to monitor the overall data size on disk. .. _metrics-vinyl-regulator: -**Regulator** +Regulator +~~~~~~~~~ The vinyl regulator decides when to take the disk IO actions. It groups activities in batches so that they will be more consistent and @@ -369,7 +358,8 @@ efficient. for vinyl trees, which is the :ref:`vinyl_memory ` parameter. -**Transactional activity** +Transactional activity +~~~~~~~~~~~~~~~~~~~~~~ * ``tnt_vinyl_tx_commit``—the counter of commits (successful transaction ends). It includes implicit commits: for example, any insert operation causes a @@ -390,7 +380,8 @@ efficient. entered a read-only state to avoid conflict temporarily. Usually the value is ``0``. If it stays non-zero for a long time, it indicates of a memory leak. -**Memory** +Memory +~~~~~~ These metrics show the state memory areas used by vinyl for caches and write buffers. @@ -413,9 +404,10 @@ buffers. :ref:`bloom filters `, bytes. -.. _metrics-vinyl-scheduler: +.. _metrics-vinyl-scheduler: -**Scheduler** +Scheduler +~~~~~~~~~ The vinyl scheduler invokes the :ref:`regulator ` and updates the related variables. This happens once per second. diff --git a/doc/monitoring/plugins.rst b/doc/monitoring/plugins.rst index 48d158fa..1d1917fa 100644 --- a/doc/monitoring/plugins.rst +++ b/doc/monitoring/plugins.rst @@ -1,27 +1,25 @@ -.. _metrics-plugins: +.. _metrics-plugins: -=============================================================================== Metrics plugins -=============================================================================== +=============== Plugins allow using a unified interface to collect metrics without worrying about the way metrics export is performed. If you want to use another DB to store metrics data, you can use an appropriate export plugin just by changing one line of code. -.. _available-plugins: +.. _available-plugins: -------------------------------------------------------------------------------- Available plugins -------------------------------------------------------------------------------- +----------------- -.. _prometheus: +.. _prometheus: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Prometheus -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~ -**Usage** +Usage +^^^^^ Import the Prometheus plugin: @@ -45,70 +43,71 @@ for details on ```` and ````. Use in Tarantool `http.server `_ as follows: -* In Tarantool `http.server v1 `_ - (currently used in `Tarantool Cartridge `_): +* In Tarantool `http.server v1 `_ + (currently used in `Tarantool Cartridge `_): - .. code-block:: lua + .. code-block:: lua - local httpd = require('http.server').new(...) - ... - httpd:route( { path = '/metrics' }, prometheus.collect_http) + local httpd = require('http.server').new(...) + ... + httpd:route( { path = '/metrics' }, prometheus.collect_http) -* In Tarantool `http.server v2 `_ - (the latest version): +* In Tarantool `http.server v2 `_ + (the latest version): - .. code-block:: lua + .. code-block:: lua - local httpd = require('http.server').new(...) - local router = require('http.router').new(...) - httpd:set_router(router) - ... - router:route( { path = '/metrics' }, prometheus.collect_http) + local httpd = require('http.server').new(...) + local router = require('http.router').new(...) + httpd:set_router(router) + ... + router:route( { path = '/metrics' }, prometheus.collect_http) -**Sample settings** +Sample settings +^^^^^^^^^^^^^^^ -* For Tarantool ``http.server`` v1: +* For Tarantool ``http.server`` v1: - .. code-block:: lua + .. code-block:: lua - metrics = require('metrics') - metrics.enable_default_metrics() - prometheus = require('metrics.plugins.prometheus') - httpd = require('http.server').new('0.0.0.0', 8080) - httpd:route( { path = '/metrics' }, prometheus.collect_http) - httpd:start() + metrics = require('metrics') + metrics.enable_default_metrics() + prometheus = require('metrics.plugins.prometheus') + httpd = require('http.server').new('0.0.0.0', 8080) + httpd:route( { path = '/metrics' }, prometheus.collect_http) + httpd:start() -* For Tarantool Cartridge (with ``http.server`` v1): +* For Tarantool Cartridge (with ``http.server`` v1): - .. code-block:: lua + .. code-block:: lua - cartridge = require('cartridge') - httpd = cartridge.service_get('httpd') - metrics = require('metrics') - metrics.enable_default_metrics() - prometheus = require('metrics.plugins.prometheus') - httpd:route( { path = '/metrics' }, prometheus.collect_http) + cartridge = require('cartridge') + httpd = cartridge.service_get('httpd') + metrics = require('metrics') + metrics.enable_default_metrics() + prometheus = require('metrics.plugins.prometheus') + httpd:route( { path = '/metrics' }, prometheus.collect_http) -* For Tarantool ``http.server`` v2: +* For Tarantool ``http.server`` v2: - .. code-block:: lua + .. code-block:: lua - metrics = require('metrics') - metrics.enable_default_metrics() - prometheus = require('metrics.plugins.prometheus') - httpd = require('http.server').new('0.0.0.0', 8080) - router = require('http.router').new({charset = "utf8"}) - httpd:set_router(router) router:route( { path = '/metrics' }, - prometheus.collect_http) - httpd:start() + metrics = require('metrics') + metrics.enable_default_metrics() + prometheus = require('metrics.plugins.prometheus') + httpd = require('http.server').new('0.0.0.0', 8080) + router = require('http.router').new({charset = "utf8"}) + httpd:set_router(router) router:route( { path = '/metrics' }, + prometheus.collect_http) + httpd:start() .. _graphite: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Graphite -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~ -**Usage** +Usage +^^^^^ Import the Graphite plugin: @@ -119,7 +118,7 @@ Import the Graphite plugin: To start automatically exporting the current values of all ``metrics.{counter,gauge,histogram}``, just call: -.. module:: metrics.plugins.graphite +.. module:: metrics.plugins.graphite .. function:: init(options) @@ -136,13 +135,13 @@ To start automatically exporting the current values of all Exported metric name is sent in the format ``.``. -.. _json: +.. _json: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~ -**Usage** +Usage +^^^^^ Import the JSON plugin: @@ -230,15 +229,14 @@ To be used in Tarantool ``http.server`` as follows: end ) -.. _plugin-specific-api: +.. _plugin-specific-api: -------------------------------------------------------------------------------- Plugin-specific API -------------------------------------------------------------------------------- +------------------- We encourage you to use the following methods **only when developing a new plugin**. -.. module:: metrics +.. module:: metrics .. function:: invoke_callbacks() @@ -256,7 +254,7 @@ We encourage you to use the following methods **only when developing a new plugi .. method:: collect() - .. NOTE:: + .. note:: You'll probably want to use ``metrics.collectors()`` instead. @@ -286,9 +284,8 @@ We encourage you to use the following methods **only when developing a new plugi .. _writing-custom-plugins: -------------------------------------------------------------------------------- Writing custom plugins -------------------------------------------------------------------------------- +---------------------- Inside your main export function: From 923f959c780d43b564232387e1789ac82aa04129 Mon Sep 17 00:00:00 2001 From: patiencedaur Date: Wed, 13 Oct 2021 14:49:52 +0300 Subject: [PATCH 5/9] Name internal links in accordance with the style guide --- doc/monitoring/api_reference.rst | 14 +++++++------- doc/monitoring/getting_started.rst | 15 ++++++++------- doc/monitoring/metrics_reference.rst | 28 ++++++++++++++-------------- doc/monitoring/plugins.rst | 12 +++--------- 4 files changed, 32 insertions(+), 37 deletions(-) diff --git a/doc/monitoring/api_reference.rst b/doc/monitoring/api_reference.rst index c01e8141..14275b35 100644 --- a/doc/monitoring/api_reference.rst +++ b/doc/monitoring/api_reference.rst @@ -1,9 +1,9 @@ -.. _metrics-api-reference: +.. _metrics-api_reference: API reference ============= -.. _collectors: +.. _metrics-api_reference-collectors: Collectors ---------- @@ -284,7 +284,7 @@ In the example above, we could derive these time series: You can also set global labels by calling ``metrics.set_global_labels({ label = value, ...})``. -.. _metrics-functions: +.. _metrics-api_reference-functions: Metrics functions ----------------- @@ -422,7 +422,7 @@ Metrics functions If youre using one of default exporters, invoke_callbacks function will be called by exporter -.. _metrics-role-functions: +.. _metrics-api_reference-role_functions: Metrics role API ---------------- @@ -483,7 +483,7 @@ Functions to call with ``metrics = require('cartridge.roles.metrics')`` in ``ini local metrics = require('cartridge.roles.metrics') metrics.set_default_labels({ ['my-custom-label'] = 'label-value' }) -.. _collecting-http-statistics: +.. _metrics-api_reference-collecting_http_statistics: Collecting HTTP requests latency statistics ------------------------------------------- @@ -562,7 +562,7 @@ latency statistics. For a more detailed example, see https://github.com/tarantool/metrics/blob/master/example/HTTP/latency_v2.lua -.. _cpu-usage-metrics: +.. _metrics-api_reference-cpu_usage_metrics: CPU usage metrics ----------------- @@ -602,7 +602,7 @@ for details. To enable it you should register callback: sum by (thread_name) (idelta(tnt_cpu_thread[$__interval])) / scalar(idelta(tnt_cpu_total[$__interval]) / tnt_cpu_count) -.. _example: +.. _metrics-api_reference-example: Examples -------- diff --git a/doc/monitoring/getting_started.rst b/doc/monitoring/getting_started.rst index ebca48c6..15643719 100644 --- a/doc/monitoring/getting_started.rst +++ b/doc/monitoring/getting_started.rst @@ -1,9 +1,9 @@ -.. _monitoring-getting-started: +.. _monitoring-getting_started: Monitoring: getting started =========================== -.. _tarantool-metrics: +.. _monitoring-getting_started-tarantool: Tarantool --------- @@ -53,9 +53,9 @@ Initialize the Prometheus Exporter, or export metrics in any other format: Now you can use the HTTP API endpoint ``/metrics`` to collect your metrics in the Prometheus format. If you need your custom metrics, see the -:ref:`API reference `. +:ref:`API reference `. -.. _metrics-http: +.. _monitoring-getting_started-http_metrics: Collect HTTP metrics -------------------- @@ -103,7 +103,7 @@ If youre using default Grafana-dashboard (link) dont change collector name, otherwise you wont see your metrics on charts -.. _instance-health-check: +.. _monitoring-getting_started-instance_health_check: Instance health check --------------------- @@ -117,7 +117,7 @@ load-balancer to check the current state of any Tarantool instance. If the insta is ready to accept the load, it will return a response with a 200 status code, if not, with a 500 status code. -.. _cartridge-role: +.. _monitoring-getting_started-cartridge_role: Cartridge role -------------- @@ -290,4 +290,5 @@ via configuration. - luajit - memory - You can see full list of default metrics in :ref:`API reference `. + You can see full list of default metrics + in :ref:`API reference metrics-api_reference-functions>`. diff --git a/doc/monitoring/metrics_reference.rst b/doc/monitoring/metrics_reference.rst index 2b951300..8a0cf272 100644 --- a/doc/monitoring/metrics_reference.rst +++ b/doc/monitoring/metrics_reference.rst @@ -16,7 +16,7 @@ General instance information: * ``tnt_read_only``—is instance in read only mode (value is 1 if true and 0 if false). -.. _memory-general: +.. _metrics-reference-memory_general: Memory general -------------- @@ -41,7 +41,7 @@ These metrics provide a picture of memory usage by the Tarantool process. For the vinyl storage engine, this is the total size of all allocated objects (struct ``txv``, struct ``vy_tx``, struct ``vy_read_interval``) and tuples pinned for those objects. -.. _memory-allocation: +.. _metrics-reference-memory_allocation: Memory allocation ----------------- @@ -76,7 +76,7 @@ Memory utilization, %: * ``tnt_slab_items_used_ratio``—tnt_slab_items_used / tnt_slab_items_size. -.. _spaces: +.. _metrics-reference-spaces: Spaces ------ @@ -108,7 +108,7 @@ These metrics provide specific information about each individual space in a Tara where ``name`` is the name of the space, and ``engine`` is the engine of the space. -.. _network: +.. _metrics-reference-network: Network ------- @@ -135,7 +135,7 @@ Requests: * ``tnt_net_requests_current``—amount of pending network requests. -.. _metrics-fibers: +.. _metrics-reference-fibers: Fibers ------ @@ -151,7 +151,7 @@ fibers count and memory usage: * ``tnt_fiber_memused``—the amount of memory that is used by fibers. -.. _metrics-operations: +.. _metrics-reference-operations: Operations ---------- @@ -179,7 +179,7 @@ Request type could be one of: * ``prepare``—SQL prepare calls * ``insert``—insert calls -.. _metrics-replication: +.. _metrics-reference-replication: Replication ----------- @@ -198,7 +198,7 @@ mechanism in Tarantool, see :ref:`this `. * ``tnt_replication__lag``—replication lag value in seconds, where ``id`` is the instance's number in the replicaset. -.. _metrics-runtime: +.. _metrics-reference-runtime: Runtime ------- @@ -207,7 +207,7 @@ Runtime * ``tnt_runtime_used``—number of bytes used for the Lua runtime. -.. _metrics-cartridge: +.. _metrics-reference-cartridge: Cartridge --------- @@ -229,7 +229,7 @@ This metric always has the label ``{delta="..."}``, which is one of: * ``max``—the difference with the fastest clock (always positive), * ``min``—the difference with the slowest clock (always negative). -.. _metrics-luajit: +.. _metrics-reference-luajit: LuaJIT metrics -------------- @@ -283,7 +283,7 @@ Allocations: * ``lj_gc_allocated``—total amount of allocated memory. -.. _metrics-psutils: +.. _metrics-reference-psutils: CPU metrics ----------- @@ -308,7 +308,7 @@ There are also the following cross-platform metrics obtained using the call ``ge * ``tnt_cpu_user_time`` - Tarantool CPU user time. * ``tnt_cpu_system_time`` - Tarantool CPU system time. -.. _metrics-vinyl: +.. _metrics-reference-vinyl: Vinyl ----- @@ -326,7 +326,7 @@ The disk metrics are used to monitor the overall data size on disk. * ``tnt_vinyl_disk_index_size``—the amount of data stored in the ``.index`` files located in the :ref:`vinyl_dir ` directory, bytes. -.. _metrics-vinyl-regulator: +.. _metrics-reference-vinyl_regulator: Regulator ~~~~~~~~~ @@ -404,7 +404,7 @@ buffers. :ref:`bloom filters `, bytes. -.. _metrics-vinyl-scheduler: +.. _metrics-reference-vinyl_scheduler: Scheduler ~~~~~~~~~ diff --git a/doc/monitoring/plugins.rst b/doc/monitoring/plugins.rst index 1d1917fa..05810fe4 100644 --- a/doc/monitoring/plugins.rst +++ b/doc/monitoring/plugins.rst @@ -8,13 +8,11 @@ worrying about the way metrics export is performed. If you want to use another DB to store metrics data, you can use an appropriate export plugin just by changing one line of code. -.. _available-plugins: +.. _metrics-plugins-available: Available plugins ----------------- -.. _prometheus: - Prometheus ~~~~~~~~~~ @@ -101,8 +99,6 @@ Sample settings prometheus.collect_http) httpd:start() -.. _graphite: - Graphite ~~~~~~~~ @@ -135,8 +131,6 @@ To start automatically exporting the current values of all Exported metric name is sent in the format ``.``. -.. _json: - JSON ~~~~ @@ -229,7 +223,7 @@ To be used in Tarantool ``http.server`` as follows: end ) -.. _plugin-specific-api: +.. _metrics-plugins-plugin-specific_api: Plugin-specific API ------------------- @@ -282,7 +276,7 @@ We encourage you to use the following methods **only when developing a new plugi :rtype: table -.. _writing-custom-plugins: +.. _metrics-plugins-custom: Writing custom plugins ---------------------- From 3cb2ec993c9a0471d0758985d3e773cbb08811d2 Mon Sep 17 00:00:00 2001 From: patiencedaur Date: Thu, 14 Oct 2021 18:07:31 +0300 Subject: [PATCH 6/9] Proofread the API reference --- doc/monitoring/api_reference.rst | 393 ++++++++++++++++--------------- 1 file changed, 203 insertions(+), 190 deletions(-) diff --git a/doc/monitoring/api_reference.rst b/doc/monitoring/api_reference.rst index 14275b35..0462d0b1 100644 --- a/doc/monitoring/api_reference.rst +++ b/doc/monitoring/api_reference.rst @@ -8,45 +8,47 @@ API reference Collectors ---------- -An application using the ``metrics`` module has 4 primitives (called "collectors") +An application using the ``metrics`` module has 4 primitives, called **collectors**, at its disposal: .. contents:: :local: :depth: 1 -A collector represents one or more observations that are changing over time. +A collector represents one or more observations that change over time. .. module:: metrics -.. _counter: +.. _metrics-api_reference-counter: counter ~~~~~~~ .. function:: counter(name [, help]) - Registers a new counter. + Register a new counter. - :param string name: Collector name. Must be unique. - :param string help: Help description. - :return: Counter object + :param string name: collector name. Must be unique. + :param string help: collector description. + :return: A counter object. :rtype: counter_obj .. class:: counter_obj + .. _metrics-api_reference-counter_inc: + .. method:: inc(num, label_pairs) - Increments an observation under ``label_pairs``. - If ``label_pairs`` didn't exist before, this creates it. + Increment the observation for ``label_pairs``. + If ``label_pairs`` doesn't exist, the method creates it. - :param number num: Increase value. - :param table label_pairs: Table containing label names as keys, + :param number num: increment value. + :param table label_pairs: table containing label names as keys, label values as values. Note that both - labels names and values in label_pairs + label names and values in ``label_pairs`` are treated as strings. - .. _counter-collect: + .. _metrics-api_reference-counter_collect: .. method:: collect() @@ -63,32 +65,34 @@ counter :rtype: table + .. _metrics-api_reference-counter_remove: + .. method:: remove(label_pairs) - Removes an observation with ``label_pairs``. + Remove the observation for ``label_pairs``. .. method:: reset(label_pairs) - Set an observation under ``label_pairs`` to 0. + Set the observation for ``label_pairs`` to 0. - :param table label_pairs: Table containing label names as keys, + :param table label_pairs: table containing label names as keys, label values as values. Note that both - labels names and values in label_pairs + label names and values in ``label_pairs`` are treated as strings. -.. _gauge: +.. _metrics-api_reference-gauge: gauge ~~~~~ .. function:: gauge(name [, help]) - Registers a new gauge. Returns a Gauge object. + Register a new gauge. - :param string name: Collector name. Must be unique. - :param string help: Help description. + :param string name: collector name. Must be unique. + :param string help: collector description. - :return: Gauge object + :return: A gauge object. :rtype: gauge_obj @@ -96,177 +100,181 @@ gauge .. method:: inc(num, label_pairs) - Same as Counter ``inc()``. + Works as the ``inc()`` function + of a :ref:`counter `.. .. method:: dec(num, label_pairs) - Same as ``inc()``, but decreases the observation. + Works as ``inc()``, but decrements the observation. .. method:: set(num, label_pairs) - Same as ``inc()``, but sets the observation. + Sets the observation for ``label_pairs`` to ``num``. .. method:: collect() Returns an array of ``observation`` objects for the given gauge. - For ``observation`` description, see - :ref:`counter_obj:collect() `. + For the description of ``observation``, see + :ref:`counter_obj:collect() `. .. method:: remove(label_pairs) - Same as Counter ``remove()``. + Works as the ``remove()`` function + of a :ref:`counter `. -.. _histogram: +.. _metrics-api_reference-histogram: histogram ~~~~~~~~~ .. function:: histogram(name [, help, buckets]) - Registers a new histogram. + Register a new histogram. - :param string name: Collector name. Must be unique. - :param string help: Help description. - :param table buckets: Histogram buckets (an array of sorted positive numbers). - Infinity bucket (``INF``) is appended automatically. - Default is ``{.005, .01, .025, .05, .075, .1, .25, .5, .75, 1.0, 2.5, 5.0, 7.5, 10.0, INF}``. + :param string name: collector name. Must be unique. + :param string help: collector description. + :param table buckets: histogram buckets (an array of sorted positive numbers). + The infinity bucket (``INF``) is appended automatically. + Default: ``{.005, .01, .025, .05, .075, .1, .25, .5, .75, 1.0, 2.5, 5.0, 7.5, 10.0, INF}``. - :return: Histogram object + :return: A histogram object. :rtype: histogram_obj .. note:: - The histogram is just a set of collectors: + A histogram is basically a set of collectors: - * ``name .. "_sum"`` - A counter holding the sum of added observations. - Contains only an empty label set. - * ``name .. "_count"`` - A counter holding the number of added observations. - Contains only an empty label set. - * ``name .. "_bucket"`` - A counter holding all bucket sizes under the label - ``le`` (low or equal). So to access a specific bucket ``x`` (``x`` is a number), - you should specify the value ``x`` for the label ``le``. + * ``name .. "_sum"``---a counter holding the sum of added observations. + * ``name .. "_count"``---a counter holding the number of added observations. + * ``name .. "_bucket"``---a counter holding all bucket sizes under the label + ``le`` (less or equal). To access a specific bucket---``x`` (where ``x`` is a number), + specify the value ``x`` for the label ``le``. .. class:: histogram_obj .. method:: observe(num, label_pairs) - Records a new value in a histogram. - This increments all buckets sizes under labels ``le`` >= ``num`` + Record a new value in a histogram. + This increments all bucket sizes under labels ``le`` >= ``num`` and labels matching ``label_pairs``. - :param number num: Value to put in the histogram. - :param table label_pairs: Table containing label names as keys, - label values as values (table). - A new value is observed by all internal counters - with these labels specified. Note that both - labels names and values in label_pairs + :param number num: value to put in the histogram. + :param table label_pairs: table containing label names as keys, + label values as values. + All internal counters that have these labels specified + observe new counter values. + Note that both label names and values in ``label_pairs`` are treated as strings. .. method:: collect() - Returns a concatenation of ``counter_obj:collect()`` across all internal - counters of ``histogram_obj``. For ``observation`` description, - see :ref:`counter_obj:collect() `. + Return a concatenation of ``counter_obj:collect()`` across all internal + counters of ``histogram_obj``. For the description of ``observation``, + see :ref:`counter_obj:collect() `. .. method:: remove(label_pairs) - Same as Counter ``remove()``. + Works as the ``remove()`` function + of a :ref:`counter `. -.. _summary: +.. _metrics-api_reference-summary: summary ~~~~~~~ .. function:: summary(name [, help, objectives]) - Registers a new summary. Quantile computation is based on the algorithm + Register a new summary. Quantile computation is based on the algorithm `"Effective computation of biased quantiles over data streams" `_ - :param string name: Collector name. Must be unique. - :param string help: Help description. - :param table objectives: A list of 'targeted' φ-quantiles in the form ``{quantile = error, ... }``. + :param string name: сollector name. Must be unique. + :param string help: collector description. + :param table objectives: a list of "targeted" φ-quantiles in the form ``{quantile = error, ... }``. For example: ``{[0.5]=0.01, [0.9]=0.01, [0.99]=0.01}``. - A targeted φ-quantile is specified in the form of a φ-quantile and tolerated - error. For example a ``{[0.5] = 0.1}`` means that the median (= 50th - percentile) should be returned with 10 percent error. Note that - percentiles and quantiles are the same concept, except percentiles are - expressed as percentages. The φ-quantile must be in the interval [0, 1]. - Note that a lower tolerated error for a φ-quantile results in higher - usage of resources (memory and CPU) to calculate the summary. - - :param table params: Table of summary parameters, used for configuring sliding - window of time. 'Sliding window' consists of several buckets to store observations. - New observations are added to each bucket. After a time period, the 'head' bucket - (bucket from which observations are collected) is reset and the next bucket becomes a - new 'head'. I.e. each bucket will store observations for - ``max_age_time * age_buckets_count`` seconds before it will be reset. - ``max_age_time`` sets the duration of each bucket lifetime, i.e., how long - observations are kept before they are discarded, in seconds - ``age_buckets_count`` sets the number of buckets of the time window. It - determines the number of buckets used to exclude observations that are - older than ``max_age_time`` from the Summary. The value is + A targeted φ-quantile is specified in the form of a φ-quantile and the tolerated + error. For example, ``{[0.5] = 0.1}`` means that the median (= 50th + percentile) must be returned with a 10 percent error. Note that + percentiles and quantiles are the same concept, except that percentiles are + expressed as percentages. The φ-quantile must be in the interval ``[0, 1]``. + A lower tolerated error for a φ-quantile results in higher memory and CPU + usage during summary calculation. + + :param table params: table of the summary parameters used to configuring the sliding + time window. This window consists of several buckets to store observations. + New observations are added to each bucket. After a time period, the head bucket + (from which observations are collected) is reset, and the next bucket becomes the + new head. This way, each bucket stores observations for + ``max_age_time * age_buckets_count`` seconds before it is reset. + ``max_age_time`` sets the duration of each bucket lifetime---that is, how + many seconds the observations are kept before they are discarded. + ``age_buckets_count`` sets the number of buckets in the sliding time window. + This variable determines the number of buckets used to exclude observations + older than ``max_age_time`` from the summary. The value is a trade-off between resources (memory and CPU for maintaining the bucket) - and how smooth the time window is moved. - Default value is `{max_age_time = math.huge, age_buckets_count = 1}` + and how smooth the time window moves. + Default value: ``{max_age_time = math.huge, age_buckets_count = 1}``. - :return: Summary object + :return: A summary object. :rtype: summary_obj .. note:: - The summary is just a set of collectors: + A summary is basically a set of collectors: - * ``name .. "_sum"`` - A counter holding the sum of added observations. - * ``name .. "_count"`` - A counter holding the number of added observations. - * ``name`` - It's holding all quantiles under observation under the label - ``quantile`` (low or equal). So to access a specific quantile ``x`` - (``x`` is a number), you should specify the value ``x`` for the label ``quantile``. + * ``name .. "_sum"``---a counter holding the sum of added observations. + * ``name .. "_count"``---a counter holding the number of added observations. + * ``name``---holds all the quantiles under observation that find themselves + under the label ``quantile`` (less or equal). + To access a specific bucket---``x`` (where ``x`` is a number), + specify the value ``x`` for the label ``quantile``. .. class:: summary_obj .. method:: observe(num, label_pairs) - Records a new value in a summary. + Record a new value in a summary. - :param number num: Value to put in the data stream. - :param table label_pairs: A table containing label names as keys, - label values as values (table). - A new value is observed by all internal counters - with these labels specified. - Label ``"quantile"`` are not allowed in ``summary``. - It will be added automatically. + :param number num: value to put in the data stream. + :param table label_pairs: a table containing label names as keys, + label values as values. + All internal counters that have these labels specified + observe new counter values. + You can't add the ``"quantile"`` label to a summary. + It is added automatically. If ``max_age_time`` and ``age_buckets_count`` are set, the observed value will be added to each bucket. - Note that both labels names and values in label_pairs + Note that both label names and values in ``label_pairs`` are treated as strings. .. method:: collect() - Returns a concatenation of ``counter_obj:collect()`` across all internal - counters of ``summary_obj``. For ``observation`` description, - see :ref:`counter_obj:collect() `. + Return a concatenation of ``counter_obj:collect()`` across all internal + counters of ``summary_obj``. For the description of ``observation``, + see :ref:`counter_obj:collect() `. If ``max_age_time`` and ``age_buckets_count`` are set, quantile observations - will be collect only from the head bucket in sliding window and not from every - bucket. If there was no observations returns NaN in values. + will be collected only from the head bucket in the sliding time window + and not from every bucket. If no observations were recorded, + the method will return NaN in the values. .. method:: remove(label_pairs) - Same as Counter ``remove()``. + Works as the ``remove()`` function + of a :ref:`counter `. -.. _labels: +.. _metrics-api_reference-labels: Labels ------ All collectors support providing ``label_pairs`` on data modification. -Labels are basically a metainfo that you associate with a metric in the format +Labels are basically pieces of metainfo that you associate with a metric in the format of key-value pairs. See tags in Graphite and labels in Prometheus. -Labels are used to differentiate the characteristics of a thing being +Labels are used to differentiate between the characteristics of a thing being measured. For example, in a metric associated with the total number of http -requests, you can use methods and statuses label pairs: +requests, you can represent methods and statuses as label pairs: .. code-block:: lua @@ -274,12 +282,12 @@ requests, you can use methods and statuses label pairs: You don't have to predefine labels in advance. -Using labels on your metrics allows you to later derive new time series -(visualize their graphs) by specifying conditions on label values. -In the example above, we could derive these time series: +With labels, you can extract new time series (visualize their graphs) +by specifying conditions regarding label values. +The example above would allow us to extract the following time series: -#. The total number of requests over time with method = "POST" (and any status). -#. The total number of requests over time with status = 500 (and any method). +#. The total number of requests over time with ``method = "POST"`` (and any status). +#. The total number of requests over time with ``status = 500`` (and any method). You can also set global labels by calling ``metrics.set_global_labels({ label = value, ...})``. @@ -291,11 +299,11 @@ Metrics functions .. function:: enable_default_metrics([include, exclude]) - Enables Tarantool metrics collections. + Enable Tarantool metrics collection. - :param table include: Table containing names of default metrics which you need to enable. + :param table include: table containing the names of the default metrics that you need to enable. - :param table exclude: Table containing names of default metrics which you need to exclude. + :param table exclude: table containing the names of the default metrics that you need to exclude. Default metrics names: @@ -319,21 +327,21 @@ Metrics functions .. function:: set_global_labels(label_pairs) - Set global labels that will be added to every observation. + Set the global labels to be added to every observation. - :param table label_pairs: Table containing label names as string keys, - label values as values (table). + :param table label_pairs: table containing label names as string keys, + label values as values. - Global labels are applied only on metrics collection and have no effect + Global labels are applied only to metrics collection. They have no effect on how observations are stored. Global labels can be changed on the fly. - Observation ``label_pairs`` has priority over global labels: - if you pass ``label_pairs`` to an observation method with the same key as + ``label_pairs`` from an observation object has priority over global labels. + If you pass ``label_pairs`` to an observation method with the same key as some global label, the method argument value will be used. - Note that both labels names and values in label_pairs are treated as strings. + Note that both label names and values in ``label_pairs`` are treated as strings. .. function:: collect() @@ -343,49 +351,49 @@ Metrics functions .. method:: unregister(collector) - Removes collector from registry + Remove a collector from the registry. :param collector_obj collector: collector that has to be removed - Example: + **Example:** - .. code-block:: lua + .. code-block:: lua - local collector = metrics.gauge('some-gauge') + local collector = metrics.gauge('some-gauge') - -- after some time we don't need it anymore + -- after a while, we don't need it anymore - metrics.registry:unregister(collector) + metrics.registry:unregister(collector) .. method:: find(kind, name) - Finds collector in registry + Find a collector in the registry. - :param string kind: collector kind ('counter', 'gauge', 'histogram' or 'summary') + :param string kind: collector kind (``counter``, ``gauge``, ``histogram``, or ``summary``) :param string name: collector name - :return: Collector object or nil + :return: A collector object or ``nil``. :rtype: collector_obj - Example: + **Example:** - .. code-block:: lua + .. code-block:: lua - local collector = metrics.gauge('some-gauge') + local collector = metrics.gauge('some-gauge') - collector = metrics.registry:find('gauge', 'some-gauge') + collector = metrics.registry:find('gauge', 'some-gauge') .. function:: register_callback(callback) - Registers a function ``callback`` which will be called right before metrics + Register a function named ``callback``, which will be called right before metrics collection on plugin export. - :param function callback: Function which takes no parameters. + :param function callback: a function that takes no parameters. - Most common usage is for gauge metrics updates. + This method is most often used for gauge metrics updates. - Example: + **Example:** .. code-block:: lua @@ -396,12 +404,12 @@ Metrics functions .. function:: unregister_callback(callback) - Unregisters a function ``callback`` which will be called right before metrics + Unregister a function named ``callback`` that is called right before metrics collection on plugin export. - :param function callback: Function which takes no parameters. + :param function callback: a function that takes no parameters. - Example: + **Example:** .. code-block:: lua @@ -412,28 +420,29 @@ Metrics functions metrics.register_callback(cpu_callback) - -- after some time we dont need that callback anymore + -- after a while, we don't need that callback function anymore metrics.unregister_callback(cpu_callback) .. function:: invoke_callbacks() - Invokes all registered callbacks. Needs to be called before each collect. - If youre using one of default exporters, - invoke_callbacks function will be called by exporter + Invoke all registered callbacks. Has to be called before each ``collect()``. + If you're using one of the default exporters, + ``invoke_callbacks()`` will be called by the exporter. .. _metrics-api_reference-role_functions: Metrics role API ---------------- -Functions to call with ``metrics = require('cartridge.roles.metrics')`` in ``init.lua`` +Below are the functions that you can call +with ``metrics = require('cartridge.roles.metrics')`` specified in your ``init.lua``. .. function:: set_export(export) - :param table export: Table containing path and format of exporting metrics. + :param table export: table containing the path and format of the exported metrics. - Configure endpoints of metrics role: + Configure the endpoints of the metrics role: .. code-block:: lua @@ -453,7 +462,7 @@ Functions to call with ``metrics = require('cartridge.roles.metrics')`` in ``ini } }) - You can add several entry points of the same format by different paths, + You can add several entry points of the same format but with different paths, like this: .. code-block:: lua @@ -472,11 +481,11 @@ Functions to call with ``metrics = require('cartridge.roles.metrics')`` in ``ini .. function:: set_default_labels(label_pairs) Add default global labels. Note that both - labels names and values in label_pairs + label names and values in ``label_pairs`` are treated as strings. :param table label_pairs: Table containing label names as string keys, - label values as values (table). + label values as values. .. code-block:: lua @@ -485,10 +494,10 @@ Functions to call with ``metrics = require('cartridge.roles.metrics')`` in ``ini .. _metrics-api_reference-collecting_http_statistics: -Collecting HTTP requests latency statistics -------------------------------------------- +Collecting HTTP request latency statistics +------------------------------------------ -``metrics`` also provides a middleware for monitoring HTTP +``metrics`` also provides middleware for monitoring HTTP (set by the `http `_ module) latency statistics. @@ -496,42 +505,48 @@ latency statistics. .. function:: configure_default_collector(type_name, name, help) - Registers a collector for the middleware and sets it as default. + Register a collector for the middleware and set it as default. - :param string type_name: Collector type: "histogram" or "summary". Default is "histogram". - :param string name: Collector name. Default is "http_server_request_latency". - :param string help: Help description. Default is "HTTP Server Request Latency". + :param string type_name: collector type: ``histogram`` or ``summary``. The default is ``histogram``. + :param string name: collector name. The default is ``http_server_request_latency``. + :param string help: collector description. The default is ``HTTP Server Request Latency``. - If a collector with the same type and name already exists in the registry, - throws an error. + **Possible errors:** + + * A collector with the same type and name already exists in the registry. .. function:: build_default_collector(type_name, name [, help]) - Registers a collector for the middleware and returns it. + Register a collector for the middleware and return it. + + :param string type_name: collector type: ``histogram`` or ``summary``. The default is ``histogram``. + :param string name: collector name. The default is ``http_server_request_latency``. + :param string help: collector description. The default is ``HTTP Server Request Latency``. + + :return: A collector object. - :param string type_name: Collector type: "histogram" or "summary". Default is "histogram". - :param string name: Collector name. Default is "http_server_request_latency". - :param string help: Help description. Default is "HTTP Server Request Latency". + **Possible errors:** - If a collector with the same type and name already exists in the registry, - throws an error. + * A collector with the same type and name already exists in the registry. .. function:: set_default_collector(collector) - Sets the default collector. + Set the default collector. - :param collector: Middleware collector object. + :param collector: middleware collector object. .. function:: get_default_collector() - Returns the default collector. + Return the default collector. If the default collector hasn't been set yet, registers it (with default ``http_middleware.build_default_collector(...)`` parameters) and sets it as default. + :return: A collector object. + .. function:: v1(handler, collector) - Latency measure wrap-up for HTTP ver. 1.x.x handler. Returns a wrapped handler. + Latency measuring wrap-up for HTTP ver. 1.x.x handler. Returns a wrapped handler. :param function handler: Handler function. :param collector: Middleware collector object. @@ -540,12 +555,11 @@ latency statistics. **Usage:** ``httpd:route(route, http_middleware.v1(request_handler, collector))`` - For a more detailed example, - see https://github.com/tarantool/metrics/blob/master/example/HTTP/latency_v1.lua + See `GitHub for a more detailed example `__. .. function:: v2(collector) - Returns the latency measure middleware for HTTP ver. 2.x.x. + Return the latency measuring middleware for HTTP ver. 2.x.x. :param collector: Middleware collector object. If not set, uses the default collector @@ -559,16 +573,15 @@ latency statistics. router:route(route, request_handler) router:use(http_middleware.v2(collector), {name = 'http_instrumentation'}) -- the second argument is optional, see HTTP docs - For a more detailed example, - see https://github.com/tarantool/metrics/blob/master/example/HTTP/latency_v2.lua + See `GitHub for a more detailed example `__. .. _metrics-api_reference-cpu_usage_metrics: CPU usage metrics ----------------- -CPU metrics work only on Linux. See :ref:`metrics reference ` -for details. To enable it you should register callback: +CPU metrics work only on Linux. See the :ref:`metrics reference ` +for details. To enable CPU metrics, first register a callback function: .. code-block:: lua @@ -579,7 +592,7 @@ for details. To enable it you should register callback: cpu_metrics.update() end) -**Collected metrics example** +**Collected metrics example:** .. code-block:: none @@ -595,7 +608,7 @@ for details. To enable it you should register callback: tnt_cpu_thread{thread_name="coio",file_name="init.lua",thread_pid="699",kind="user"} 44 tnt_cpu_thread{thread_name="coio",file_name="init.lua",thread_pid="11",kind="system"} 294 -**Prometheus query aggregated by thread name** +**Prometheus query aggregated by thread name:** .. code-block:: text @@ -607,13 +620,13 @@ for details. To enable it you should register callback: Examples -------- -Below are examples of using metrics primitives. +Below are some examples of using metrics primitives. -Notice that this usage is independent of export-plugins such as -Prometheus / Graphite / etc. For documentation on plugins usage, see -their the :ref:`Metrics plugins ` section. +Notice that this usage is independent of export plugins such as +Prometheus, Graphite, etc. For documentation on how to use the plugins, see +the :ref:`Metrics plugins ` section. -Using counters: +**Using counters:** .. code-block:: lua @@ -625,7 +638,7 @@ Using counters: -- somewhere in the HTTP requests middleware: http_requests_total_counter:inc(1, {method = 'GET'}) -Using gauges: +**Using gauges:** .. code-block:: lua @@ -641,7 +654,7 @@ Using gauges: cpu_usage_gauge:set(current_cpu_usage, {app = 'tarantool'}) end) -Using histograms: +**Using histograms:** .. code-block:: lua @@ -651,7 +664,7 @@ Using histograms: local http_requests_latency_hist = metrics.histogram( 'http_requests_latency', 'HTTP requests total', {2, 4, 6}) - -- somewhere in the HTTP requests middleware: + -- somewhere in the HTTP request middleware: local t0 = fiber.clock() observable_function() @@ -660,7 +673,7 @@ Using histograms: local latency = t1 - t0 http_requests_latency_hist:observe(latency) -Using summaries: +**Using summaries:** .. code-block:: lua From 20e31607503717afcba3388551946d0076188ea4 Mon Sep 17 00:00:00 2001 From: patiencedaur Date: Tue, 19 Oct 2021 17:27:31 +0300 Subject: [PATCH 7/9] More proofreading --- doc/monitoring/getting_started.rst | 118 +++++++++++++++-------------- doc/monitoring/index.rst | 4 +- doc/monitoring/plugins.rst | 76 +++++++++---------- 3 files changed, 101 insertions(+), 97 deletions(-) diff --git a/doc/monitoring/getting_started.rst b/doc/monitoring/getting_started.rst index 15643719..a3ae5a20 100644 --- a/doc/monitoring/getting_started.rst +++ b/doc/monitoring/getting_started.rst @@ -8,7 +8,7 @@ Monitoring: getting started Tarantool --------- -First, you need to install the ``metrics`` package: +First, install the ``metrics`` package: .. code-block:: console @@ -27,13 +27,13 @@ Set a global label for your metrics: metrics.set_global_labels({alias = 'alias'}) -Enable default Tarantool metrics such as network, memory, operations, etc: +Enable default Tarantool metrics such as network, memory, operations, etc.: .. code-block:: lua metrics.enable_default_metrics() -Initialize the Prometheus Exporter, or export metrics in any other format: +Initialize the Prometheus exporter or export metrics in another format: .. code-block:: lua @@ -52,7 +52,7 @@ Initialize the Prometheus Exporter, or export metrics in any other format: } Now you can use the HTTP API endpoint ``/metrics`` to collect your metrics -in the Prometheus format. If you need your custom metrics, see the +in the Prometheus format. To learn how to obtain custom metrics, check the :ref:`API reference `. .. _monitoring-getting_started-http_metrics: @@ -60,25 +60,25 @@ in the Prometheus format. If you need your custom metrics, see the Collect HTTP metrics -------------------- -To enable collection of HTTP metrics, you need to create collector +To enable the collection of HTTP metrics, you need to create a collector first. -Using HTTP v1: +Using HTTP v.1: .. code-block:: lua local httpd = require('http.server').new(ip, port) - -- Create summary latency collector + -- Create a summary collector for latency local collector = metrics.http_middleware.build_default_collector('summary') - -- Set route handler with summary latency collection + -- Set a route handler for latency summary collection httpd:route({ path = '/path-1', method = 'POST' }, metrics.http_middleware.v1(handler_1, collector)) httpd:route({ path = '/path-2', method = 'GET' }, metrics.http_middleware.v1(handler_2, collector)) -- Start HTTP routing httpd:start() -Using HTTP v2: +Using HTTP v.2: .. code-block:: lua @@ -88,19 +88,21 @@ Using HTTP v2: router:route({ path = '/path-1', method = 'POST' }, handler_1) router:route({ path = '/path-2', method = 'GET' }, handler_2) - -- Create summary latency collector + -- Create a summary collector for latency local collector = metrics.http_middleware.build_default_collector('summary') - -- Set router summary latency collection middleware + -- Set middleware for the router to perform latency summary collection router:use(metrics.http_middleware.v2(collector), { name = 'latency_instrumentation' }) - -- Start HTTP routing using configured router + -- Start HTTP routing using the configured router httpd:set_router(router) httpd:start() -Note that you need only one collector to collect all http metrics. -If youre using default Grafana-dashboard (link) dont change collector name, -otherwise you wont see your metrics on charts +You can collect all HTTP metrics with a single collector. +If you're using the default +:ref:`Grafana dashboard `, +don't change the default collector name. +Otherwise, your metrics won't appear on the charts. .. _monitoring-getting_started-instance_health_check: @@ -108,28 +110,29 @@ otherwise you wont see your metrics on charts Instance health check --------------------- -In production environments Tarantool Cluster usually has a large number of so called -"routers", Tarantool instances that handle input load and it is required to evenly -distribute the load. Various load-balancers are used for this, but any load-balancer -have to know which "routers" are ready to accept the load at that very moment. Metrics -library has a special plugin that creates an http handler that can be used by the -load-balancer to check the current state of any Tarantool instance. If the instance -is ready to accept the load, it will return a response with a 200 status code, if not, -with a 500 status code. +In production environments, Tarantool Cartridge usually has a large number of so-called +routers, Tarantool instances that handle input load. +Various load balancers help distribute that load evenly. +However, any load balancer has to "know" +which routers are ready to accept the load at the moment. +The Tarantool metrics library has a special plugin that creates an HTTP handler, +which the load balancer can use to check the current state of any Tarantool instance. +If the instance is ready to accept the load, it will return a response with a 200 status code, +and if not, with a 500 status code. .. _monitoring-getting_started-cartridge_role: Cartridge role -------------- -``cartridge.roles.metrics`` is a role for -`Tarantool Cartridge `_. +``cartridge.roles.metrics`` is a +`Tarantool Cartridge `__ role. It allows using default metrics in a Cartridge application and manage them -via configuration. +via Cartridge configuration. **Usage** -#. Add ``metrics`` package to dependencies in the ``.rockspec`` file. +#. Add the ``metrics`` package to dependencies in the ``.rockspec`` file. Make sure that you are using version **0.3.0** or higher. .. code-block:: lua @@ -140,9 +143,9 @@ via configuration. ... } -#. Make sure that you have ``cartridge.roles.metrics`` +#. Make sure that ``cartridge.roles.metrics`` is included in the roles list in ``cartridge.cfg`` - in your entry-point file (e.g. ``init.lua``). + in your entry point file (for example, ``init.lua``): .. code-block:: lua @@ -155,12 +158,12 @@ via configuration. }, }) -#. To view metrics via API endpoints, use ``set_export``. +#. To get metrics via API endpoints, use ``set_export``. .. note:: - ``set_export`` has lower priority than clusterwide config - and could be overriden by the metrics config. + ``set_export`` has lower priority than clusterwide configuration + and can be overridden by the metrics configuration. .. code-block:: lua @@ -180,8 +183,8 @@ via configuration. } }) - You can add several entry points of the same format by different paths, - like this: + You can add several endpoints of the same format with different paths. + For example: .. code-block:: lua @@ -196,22 +199,23 @@ via configuration. }, }) - The metrics will be available on the path specified in ``path`` in the format + The metrics will be available on the path specified in ``path``, in the format specified in ``format``. -#. Enable role in the interface: +#. Enable the role in the interface: .. image:: images/role-enable.png :align: center - Since version **0.6.0** metrics role is permanent and enabled on instances by default. + Since version **0.6.0**, the metrics role is permanent and enabled on instances by default. -#. After role initialization, default metrics will be enabled and the global - label ``'alias'`` will be set. **Note** that ``'alias'`` label value is set by - instance :ref:`configuration option ` ``alias`` or ``instance_name`` (since **0.6.1**). +#. After the role has been initialized, the default metrics will be enabled + and the global label ``'alias'`` will be set. + **Note** that the ``'alias'`` label value is set by the ``alias`` or ``instance_name`` + instance :ref:`configuration option ` (since **0.6.1**). - If you need to use the functionality of any - metrics package, you may get it as a Cartridge service and use it like + To use the functionality of any + metrics package, you can get it as a Cartridge service and use it like a regular package after ``require``: .. code-block:: lua @@ -219,14 +223,14 @@ via configuration. local cartridge = require('cartridge') local metrics = cartridge.service_get('metrics') -#. There is an ability in Tarantool Cartridge >= ``'2.4.0'`` to set a zone for each - server in cluster. If zone was set for the server ``'zone'`` label for all metrics - of this server will be added. +#. Since Tarantool Cartridge ``'2.4.0'``, you can set a zone for each + instance in the cluster. When a zone is set, all the metrics on the instance + receive the ``'zone'`` label. -#. To change metrics HTTP path in **runtime**, you may use the following configuration - (to learn more about Cartridge configuration, see - `this `_). - We don't recommend to use it to set up metrics role, use ``set_export`` instead. +#. To change the HTTP path for a metric in **runtime**, + you can use the configuration below. + `Learn more about Cartridge configuration `_). + It is not recommended to set up the metrics role in this way. Use ``set_export`` instead. .. code-block:: yaml @@ -242,7 +246,7 @@ via configuration. .. image:: images/role-config.png :align: center -#. To set custom global labels, you may use the following configuration. +#. To set custom global labels, you can use the following configuration: .. code-block:: yaml @@ -253,16 +257,15 @@ via configuration. global-labels: my-custom-label: label-value - **OR** use ``set_default_labels`` function in ``init.lua``. + Another option is to invoke the ``set_default_labels`` function in ``init.lua``: .. code-block:: lua local metrics = require('cartridge.roles.metrics') metrics.set_default_labels({ ['my-custom-label'] = 'label-value' }) -#. To choose which default metrics are exported, you may use the following configuration. - - When you add include section, only metrics from this section are exported: +#. To choose the default metrics to be exported, you can use the configuration below. + If you add the include section, only the metrics from this section will be exported: .. code-block:: yaml @@ -276,7 +279,8 @@ via configuration. - luajit - memory - When you add exclude section, metrics from this section are removed from default metrics list: + When you add the exclude section, + the metrics from this section will be removed from the default metrics list: .. code-block:: yaml @@ -290,5 +294,5 @@ via configuration. - luajit - memory - You can see full list of default metrics - in :ref:`API reference metrics-api_reference-functions>`. + For the full list of default metrics, refer to the + :ref:`API reference `. diff --git a/doc/monitoring/index.rst b/doc/monitoring/index.rst index 5074a79e..b6e88137 100644 --- a/doc/monitoring/index.rst +++ b/doc/monitoring/index.rst @@ -4,8 +4,8 @@ Monitoring ========== Monitoring is the process of measuring and tracking Tarantool performance -according to key metrics influencing it. These metrics are typically monitored -in real time, allowing you to identify or predict issues. +based on metrics. The metrics are typically monitored +in real time, which allows you to identify or predict issues. This chapter includes the following sections: diff --git a/doc/monitoring/plugins.rst b/doc/monitoring/plugins.rst index 05810fe4..ec4fd607 100644 --- a/doc/monitoring/plugins.rst +++ b/doc/monitoring/plugins.rst @@ -3,9 +3,9 @@ Metrics plugins =============== -Plugins allow using a unified interface to collect metrics without -worrying about the way metrics export is performed. -If you want to use another DB to store metrics data, you can use an +Plugins let you collect metrics through a unified interface +without worrying about the way metrics export works. +If you want to use another DB to store metrics data, you can enable an appropriate export plugin just by changing one line of code. .. _metrics-plugins-available: @@ -19,13 +19,13 @@ Prometheus Usage ^^^^^ -Import the Prometheus plugin: +Import the plugin: .. code-block:: lua local prometheus = require('metrics.plugins.prometheus') -Further, use the ``prometheus.collect_http()`` function, which returns: +Then use the ``prometheus.collect_http()`` function, which returns: .. code-block:: lua @@ -39,9 +39,10 @@ See the `Prometheus exposition format `_ for details on ```` and ````. -Use in Tarantool `http.server `_ as follows: +With Tarantool `http.server `__, +use this plugin as follows: -* In Tarantool `http.server v1 `_ +* With Tarantool `http.server v.1 `_ (currently used in `Tarantool Cartridge `_): .. code-block:: lua @@ -50,7 +51,7 @@ Use in Tarantool `http.server `_ as follows: ... httpd:route( { path = '/metrics' }, prometheus.collect_http) -* In Tarantool `http.server v2 `_ +* With Tarantool `http.server v.2 `_ (the latest version): .. code-block:: lua @@ -64,7 +65,7 @@ Use in Tarantool `http.server `_ as follows: Sample settings ^^^^^^^^^^^^^^^ -* For Tarantool ``http.server`` v1: +* For Tarantool ``http.server`` v.1: .. code-block:: lua @@ -75,7 +76,7 @@ Sample settings httpd:route( { path = '/metrics' }, prometheus.collect_http) httpd:start() -* For Tarantool Cartridge (with ``http.server`` v1): +* For Tarantool Cartridge (with ``http.server`` v.1): .. code-block:: lua @@ -86,7 +87,7 @@ Sample settings prometheus = require('metrics.plugins.prometheus') httpd:route( { path = '/metrics' }, prometheus.collect_http) -* For Tarantool ``http.server`` v2: +* For Tarantool ``http.server`` v.2: .. code-block:: lua @@ -105,31 +106,31 @@ Graphite Usage ^^^^^ -Import the Graphite plugin: +Import the plugin: .. code-block:: lua local graphite = require('metrics.plugins.graphite') To start automatically exporting the current values of all -``metrics.{counter,gauge,histogram}``, just call: +``metrics.{counter,gauge,histogram}``, call the following function: .. module:: metrics.plugins.graphite .. function:: init(options) - :param table options: Possible options: + :param table options: possible options: - * ``prefix`` (string) - metrics prefix (default is ``'tarantool'``); - * ``host`` (string) - graphite server host (default is ``'127.0.0.1'``); - * ``port`` (number) - graphite server port (default is ``2003``); - * ``send_interval`` (number) - metrics collect interval in seconds - (default is ``2``); + * ``prefix`` (string): metrics prefix (``'tarantool'`` by default) + * ``host`` (string): Graphite server host (``'127.0.0.1'`` by default) + * ``port`` (number): Graphite server port (``2003`` by default) + * ``send_interval`` (number): metrics collection interval in seconds + (``2`` by default) - This creates a background fiber that periodically sends all metrics to + This function creates a background fiber that periodically sends all metrics to a remote Graphite server. - Exported metric name is sent in the format ``.``. + Exported metric names are formatted as follows: ``.``. JSON ~~~~ @@ -137,7 +138,7 @@ JSON Usage ^^^^^ -Import the JSON plugin: +Import the plugin: .. code-block:: lua @@ -168,11 +169,11 @@ Import the JSON plugin: .. IMPORTANT:: - Values can be ``+-math.huge``, ``math.huge * 0``. Then: + The values can also be ``+-math.huge`` and ``math.huge * 0``. In such case: - * ``math.huge`` is serialized to ``"inf"`` - * ``-math.huge`` is serialized to ``"-inf"`` - * ``math.huge * 0`` is serialized to ``"nan"`` + * ``math.huge`` is serialized to ``"inf"`` + * ``-math.huge`` is serialized to ``"-inf"`` + * ``math.huge * 0`` is serialized to ``"nan"``. **Example** @@ -205,7 +206,7 @@ Import the JSON plugin: } ] -To be used in Tarantool ``http.server`` as follows: +Use the JSON plugin with Tarantool ``http.server`` as follows: .. code-block:: lua @@ -228,21 +229,21 @@ To be used in Tarantool ``http.server`` as follows: Plugin-specific API ------------------- -We encourage you to use the following methods **only when developing a new plugin**. +We encourage you to use the following methods **only when you're developing a new plugin**. .. module:: metrics .. function:: invoke_callbacks() - Invokes the function registered via + Invoke a function registered via ``metrics.register_callback()``. Used in exporters. .. function:: collectors() - Designed to be used in exporters in favor of ``metrics.collect()``. + List all collectors in the registry. Designed to be used in exporters. - :return: a list of created collectors + :return: A list of created collectors. .. class:: collector_object @@ -262,8 +263,7 @@ We encourage you to use the following methods **only when developing a new plugi end end - :return: Concatenation of ``observation`` objects across all - created collectors. + :return: A concatenation of ``observation`` objects across all created collectors. .. code-block:: lua @@ -278,21 +278,21 @@ We encourage you to use the following methods **only when developing a new plugi .. _metrics-plugins-custom: -Writing custom plugins ----------------------- +Creating custom plugins +----------------------- -Inside your main export function: +Include the following in your main export function: .. code-block:: lua - -- Invoke all callbacks registered via `metrics.register_callback()`. + -- Invoke all callbacks registered via `metrics.register_callback()` metrics.invoke_callbacks() -- Loop over collectors for _, c in pairs(metrics.collectors()) do ... - -- Loop over instant observations in the collector. + -- Loop over instant observations in the collector for _, obs in pairs(c:collect()) do -- Export observation `obs` ... From 2b21ddae92e63adfff7109570c2edaa482306ad2 Mon Sep 17 00:00:00 2001 From: patiencedaur Date: Tue, 19 Oct 2021 18:41:32 +0300 Subject: [PATCH 8/9] Refactor the metrics reference --- doc/monitoring/metrics_reference.rst | 700 ++++++++++++++++++--------- 1 file changed, 459 insertions(+), 241 deletions(-) diff --git a/doc/monitoring/metrics_reference.rst b/doc/monitoring/metrics_reference.rst index 8a0cf272..c6eb478c 100644 --- a/doc/monitoring/metrics_reference.rst +++ b/doc/monitoring/metrics_reference.rst @@ -10,36 +10,55 @@ General metrics General instance information: -* ``tnt_cfg_current_time``—instance system time in the Unix timestamp format. +.. container:: table -* ``tnt_info_uptime``—time in seconds since instance has started. + .. list-table:: + :widths: 25 75 + :header-rows: 0 -* ``tnt_read_only``—is instance in read only mode (value is 1 if true and 0 if false). + * - ``tnt_cfg_current_time`` + - Instance system time in the Unix timestamp format + * - ``tnt_info_uptime`` + - Time in seconds since the instance has started + * - ``tnt_read_only`` + - Indicates if the instance is in read-only mode (``1`` if true, ``0`` if false) .. _metrics-reference-memory_general: Memory general -------------- -These metrics provide a picture of memory usage by the Tarantool process. - -* ``tnt_info_memory_cache``—number of - bytes in the cache for the tuples stored for the vinyl storage engine. - -* ``tnt_info_memory_data``—number of bytes used for storing user data (the tuples) - with the memtx engine and with level 0 of the vinyl engine, without taking memory fragmentation into account. - -* ``tnt_info_memory_index``—number of bytes used for indexing user data, - including memtx and vinyl memory tree extents, the vinyl page index, and the vinyl bloom filters. - -* ``tnt_info_memory_lua``—number of bytes used for the Lua runtime. - Lua memory is bounded by 2 GB per instance. Monitoring this metric can prevent memory overflow. - -* ``tnt_info_memory_net``—number of bytes used for network input/output buffers. - -* ``tnt_info_memory_tx``—number of bytes in use by active transactions. - For the vinyl storage engine, this is the total size of all allocated objects - (struct ``txv``, struct ``vy_tx``, struct ``vy_read_interval``) and tuples pinned for those objects. +The following metrics provide a picture of memory usage by the Tarantool process. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_info_memory_cache`` + - Number of bytes in the cache used to store + tuples with the vinyl storage engine. + * - ``tnt_info_memory_data`` + - Number of bytes used to store user data (tuples) + with the memtx engine and with level 0 of the vinyl engine, + without regard for memory fragmentation. + * - ``tnt_info_memory_index`` + - Number of bytes used for indexing user data. + Includes memtx and vinyl memory tree extents, + the vinyl page index, and the vinyl bloom filters. + * - ``tnt_info_memory_lua`` + - Number of bytes used for the Lua runtime. + The Lua memory is limited to 2 GB per instance. + Monitoring this metric can prevent memory overflow. + * - ``tnt_info_memory_net`` + - Number of bytes used for network input/output buffers. + * - ``tnt_info_memory_tx`` + - Number of bytes in use by active transactions. + For the vinyl storage engine, + this is the total size of all allocated objects + (struct ``txv``, struct ``vy_tx``, struct ``vy_read_interval``) + and tuples pinned for those objects. .. _metrics-reference-memory_allocation: @@ -48,361 +67,553 @@ Memory allocation Provides a memory usage report for the slab allocator. The slab allocator is the main allocator used to store tuples. -This can be used to monitor the total memory usage and memory fragmentation. +The following metrics help monitor the total memory usage and memory fragmentation. To learn more about use cases, refer to the -:ref:`documentation for box.slab submodule `. +:ref:`box.slab submodule documentation `. Available memory, bytes: -* ``tnt_slab_quota_size``—the amount of memory available to store tuples and indexes, equals ``memtx_memory``. +.. container:: table -* ``tnt_slab_arena_size``—the total memory used for tuples and indexes together (including allocated, but currently free slabs). + .. list-table:: + :widths: 25 75 + :header-rows: 0 -* ``tnt_slab_items_size``—the total amount of memory (including allocated, but currently free slabs) used only for tuples, no indexes. + * - ``tnt_slab_quota_size`` + - Amount of memory available to store tuples and indexes. + Is equal to ``memtx_memory``. + * - ``tnt_slab_arena_size`` + - Total memory available to store both tuples and indexes. + Includes allocated but currently free slabs. + * - ``tnt_slab_items_size`` + - Total amount of memory available to store only tuples and not indexes. + Includes allocated but currently free slabs. Memory usage, bytes: -* ``tnt_slab_quota_used``—the amount of memory that is already reserved by the slab allocator. +.. container:: table -* ``tnt_slab_arena_used``—the efficient memory used for storing tuples and indexes together (omitting allocated, but currently free slabs). + .. list-table:: + :widths: 25 75 + :header-rows: 0 -* ``tnt_slab_items_used``—the efficient amount of memory (omitting allocated, but currently free slabs) used only for tuples, no indexes. + * - ``tnt_slab_quota_used`` + - The amount of memory that is already reserved by the slab allocator. + * - ``tnt_slab_arena_used`` + - The effective memory used to store both tuples and indexes. + Disregards allocated but currently free slabs. + * - ``tnt_slab_items_used`` + - The effective memory used to store only tuples and not indexes. + Disregards allocated but currently free slabs. Memory utilization, %: -* ``tnt_slab_quota_used_ratio``—tnt_slab_quota_used / tnt_slab_quota_size. +.. container:: table -* ``tnt_slab_arena_used_ratio``—tnt_slab_arena_used / tnt_slab_arena_used. + .. list-table:: + :widths: 25 75 + :header-rows: 0 -* ``tnt_slab_items_used_ratio``—tnt_slab_items_used / tnt_slab_items_size. + * - ``tnt_slab_quota_used_ratio`` + - ``tnt_slab_quota_used / tnt_slab_quota_size`` + * - ``tnt_slab_arena_used_ratio`` + - ``tnt_slab_arena_used / tnt_slab_arena_size`` + * - ``tnt_slab_items_used_ratio`` + - ``tnt_slab_items_used / tnt_slab_items_size`` .. _metrics-reference-spaces: Spaces ------ -These metrics provide specific information about each individual space in a Tarantool instance: - -* ``tnt_space_len``—number of records in the space. - This metric always has 2 labels: ``{name="test", engine="memtx"}``, - where ``name`` is the name of the space, and - ``engine`` is the engine of the space. - -* ``tnt_space_bsize``—the total number of bytes in all tuples. - This metric always has 2 labels: ``{name="test", engine="memtx"}``, - where ``name`` is the name of the space, and - ``engine`` is the engine of the space. - -* ``tnt_space_index_bsize``—the total number of bytes taken by the index. - This metric always has 2 labels: ``{name="test", index_name="pk"}``, - where ``name`` is the name of the space, and - ``index_name`` is the name of the index. - -* ``tnt_space_total_bsize``—the total size of tuples and all indexes in space. - This metric always has 2 labels: ``{name="test", engine="memtx"}``, - where ``name`` is the name of the space, and - ``engine`` is the engine of the space. - -* ``tnt_space_count``—the total tuples count for vinyl. - This metric always has labels—``{name="test", engine="vinyl"}``, - where ``name`` is the name of the space, and - ``engine`` is the engine of the space. +The following metrics provide specific information +about each individual space in a Tarantool instance. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_space_len`` + - Number of records in the space. + This metric always has 2 labels: ``{name="test", engine="memtx"}``, + where ``name`` is the name of the space and + ``engine`` is the engine of the space. + * - ``tnt_space_bsize`` + - Total number of bytes in all tuples. + This metric always has 2 labels: ``{name="test", engine="memtx"}``, + where ``name`` is the name of the space + and ``engine`` is the engine of the space. + * - ``tnt_space_index_bsize`` + - Total number of bytes taken by the index. + This metric always has 2 labels: ``{name="test", index_name="pk"}``, + where ``name`` is the name of the space and + ``index_name`` is the name of the index. + * - ``tnt_space_total_bsize`` + - Total size of tuples and all indexes in the space. + This metric always has 2 labels: ``{name="test", engine="memtx"}``, + where ``name`` is the name of the space and + ``engine`` is the engine of the space. + * - ``tnt_space_count`` + - Total tuple count for vinyl. + This metric always has 2 labels: ``{name="test", engine="vinyl"}``, + where ``name`` is the name of the space and + ``engine`` is the engine of the space. .. _metrics-reference-network: Network ------- -Network activity stats. This can be used to monitor network load, usage peaks and traffic drops. +Network activity stats. +These metrics can be used to monitor network load, usage peaks, and traffic drops. Sent bytes: -* ``tnt_net_sent_total``—bytes sent from this instance over network since instance start time. +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + * - ``tnt_net_sent_total`` + - Bytes sent from the instance over the network since the instance's start time + Received bytes: -* ``tnt_net_received_total``—bytes this instance has received since instance start time. +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_net_received_total`` + - Bytes received by the instance since start time Connections: -* ``tnt_net_connections_total``—number of incoming network connections since instance start time. +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 -* ``tnt_net_connections_current``—number of active network connections. + * - ``tnt_net_connections_total`` + - Number of incoming network connections since the instance's start time + * - ``tnt_net_connections_current`` + - Number of active network connections Requests: -* ``tnt_net_requests_total``—number of network requests this instance has handled since instance start time. +.. container:: table -* ``tnt_net_requests_current``—amount of pending network requests. + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_net_requests_total`` + - Number of network requests the instance has handled since its start time + * - ``tnt_net_requests_current`` + - Number of pending network requests .. _metrics-reference-fibers: Fibers ------ -Provides the statistics of :ref:`fibers `. If your app creates a lot of fibers, it can be used for monitoring -fibers count and memory usage: - -* ``tnt_fiber_count``—number of fibers. +Provides the statistics for :ref:`fibers `. +If your application creates a lot of fibers, +you can use the metrics below to monitor fiber count and memory usage. -* ``tnt_fiber_csw``—overall amount of fibers context switches. +.. container:: table -* ``tnt_fiber_memalloc``—the amount of memory that is reserved for fibers. + .. list-table:: + :widths: 25 75 + :header-rows: 0 -* ``tnt_fiber_memused``—the amount of memory that is used by fibers. + * - ``tnt_fiber_count`` + - Number of fibers + * - ``tnt_fiber_csw`` + - Overall number of fiber context switches + * - ``tnt_fiber_memalloc`` + - Amount of memory reserved for fibers + * - ``tnt_fiber_memused`` + - Amount of memory used by fibers .. _metrics-reference-operations: Operations ---------- -Number of iproto requests this instance has processed, aggregated by request type. -It can be used to find out which type of operation clients make more often. - -* ``tnt_stats_op_total``—total number of calls since server start - -That metric have ``operation`` label to be able to distinguish different request types, e.g.: -``{operation="select"}`` - -Request type could be one of: - -* ``delete``—delete calls -* ``error``—requests resulted in an error -* ``update``—update calls -* ``call``—requests to execute stored procedures -* ``auth``—authentication requests -* ``eval``—calls to evaluate lua code -* ``replace``—replace call -* ``execute``—execute SQL calls -* ``select``—select calls -* ``upsert``—upsert calls -* ``prepare``—SQL prepare calls -* ``insert``—insert calls +You can collect iproto requests an instance has processed +and aggregate them by request type. +This may help you find out what operations your clients perform most often. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_stats_op_total`` + - Total number of calls since server start + +To distinguish between request types, this metric has the ``operation`` label. +For example, it can look as follows: ``{operation="select"}``. +For the possible request types, check the table below. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``auth`` + - Authentication requests + * - ``call`` + - Requests to execute stored procedures + * - ``delete`` + - Delete calls + * - ``error`` + - Requests resulted in an error + * - ``eval`` + - Calls to evaluate Lua code + * - ``execute`` + - Execute SQL calls + * - ``insert`` + - Insert calls + * - ``prepare`` + - SQL prepare calls + * - ``replace`` + - Replace calls + * - ``select`` + - Select calls + * - ``update`` + - Update calls + * - ``upsert`` + - Upsert calls .. _metrics-reference-replication: Replication ----------- -Provides information of current replication status. To learn more about replication -mechanism in Tarantool, see :ref:`this `. +Provides the current replication status. +Learn more about :ref:`replication in Tarantool `. -* ``tnt_info_lsn``—LSN of the instance. +.. container:: table -* ``tnt_info_vclock``—LSN number in vclock. This metric always has label ``{id="id"}``, - where ``id`` is the instance's number in the replicaset. + .. list-table:: + :widths: 25 75 + :header-rows: 0 -* ``tnt_replication_replica__lsn`` / ``tnt_replication_master__lsn``—LSN of master/replica, where - ``id`` is the instance's number in the replicaset. - -* ``tnt_replication__lag``—replication lag value in seconds, where - ``id`` is the instance's number in the replicaset. + * - ``tnt_info_lsn`` + - LSN of the instance. + * - ``tnt_info_vclock`` + - LSN number in vclock. + This metric always has the label ``{id="id"}``, + where ``id`` is the instance's number in the replica set. + * - ``tnt_replication_replica__lsn`` / ``tnt_replication_master__lsn`` + - LSN of the master/replica, where + ``id`` is the instance's number in the replica set. + * - ``tnt_replication__lag`` + - Replication lag value in seconds, where + ``id`` is the instance's number in the replica set. .. _metrics-reference-runtime: Runtime ------- -* ``tnt_runtime_lua``—Lua garbage collector size in bytes. +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 -* ``tnt_runtime_used``—number of bytes used for the Lua runtime. + * - ``tnt_runtime_lua`` + - Lua garbage collector size in bytes + * - ``tnt_runtime_used`` + - Number of bytes used for the Lua runtime .. _metrics-reference-cartridge: Cartridge --------- -``tnt_cartridge_issues``—number of -:ref:`issues of instance `. -This metric always has label ``{level="critical"}``, where -``level`` is the level of the issue: +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 -* ``critical`` level is associated with critical - instance problems, for example when memory used ratio is more than 90%. -* ``warning`` level is associated with - other cluster problems, e.g. replication issues on instance. + * - ``tnt_cartridge_issues`` + - Number of :ref:`instance issues `. + This metric always has the label ``{level="critical"}``, where + ``level`` is the level of the issue: + * ``critical`` is associated with critical instance problems, + such as the case when there is more than 90% memory used. + * ``warning`` is associated with other cluster problems, + such as replication issues on the instance. -``tnt_clock_delta``—the clock drift across the cluster. -This metric always has the label ``{delta="..."}``, which is one of: + * - ``tnt_clock_delta`` + - Clock drift across the cluster. + This metric always has the label ``{delta="..."}``, + which has the following possible values: -* ``max``—the difference with the fastest clock (always positive), -* ``min``—the difference with the slowest clock (always negative). + * ``max``---difference with the fastest clock (always positive) + * ``min``---difference with the slowest clock (always negative). .. _metrics-reference-luajit: LuaJIT metrics -------------- -LuaJIT metrics help understand the stage of Lua garbage collector. -They are available in Tarantool 2.6 and later. +LuaJIT metrics provide an insight into the work of the Lua garbage collector. +These metrics are available in Tarantool 2.6 and later. General JIT metrics: -* ``lj_jit_snap_restore``—overall number of snap restores. +.. container:: table -* ``lj_jit_trace_num``—number of JIT traces. + .. list-table:: + :widths: 25 75 + :header-rows: 0 -* ``lj_jit_trace_abort``—overall number of abort traces. - -* ``lj_jit_mcode_size``—total size of all allocated machine code areas. + * - ``lj_jit_snap_restore`` + - Overall number of snap restores + * - ``lj_jit_trace_num`` + - Number of JIT traces + * - ``lj_jit_trace_abort`` + - Overall number of abort traces + * - ``lj_jit_mcode_size`` + - Total size of allocated machine code areas JIT strings: -* ``lj_strhash_hit``—number of strings being interned. - -* ``lj_strhash_miss``—total number of string allocations. - -GC steps: - -* ``lj_gc_steps_atomic``—count of incremental GC steps (atomic state). - -* ``lj_gc_steps_sweepstring``—count of incremental GC steps (sweepstring state). +.. container:: table -* ``lj_gc_steps_finalize``—count of incremental GC steps (finalize state). + .. list-table:: + :widths: 25 75 + :header-rows: 0 -* ``lj_gc_steps_sweep``—count of incremental GC steps (sweep state). + * - ``lj_strhash_hit`` + - Number of strings being interned + * - ``lj_strhash_miss`` + - Total number of string allocations -* ``lj_gc_steps_propagate``—count of incremental GC steps (propagate state). +GC steps: -* ``lj_gc_steps_pause``—count of incremental GC steps (pause state). +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``lj_gc_steps_atomic`` + - Count of incremental GC steps (atomic state) + * - ``lj_gc_steps_sweepstring`` + - Count of incremental GC steps (sweepstring state) + * - ``lj_gc_steps_finalize`` + - Count of incremental GC steps (finalize state) + * - ``lj_gc_steps_sweep`` + - Count of incremental GC steps (sweep state) + * - ``lj_gc_steps_propagate`` + - Count of incremental GC steps (propagate state) + * - ``lj_gc_steps_pause`` + - Count of incremental GC steps (pause state) Allocations: -* ``lj_gc_strnum``—number of allocated ``string`` objects. - -* ``lj_gc_tabnum``—number of allocated ``table`` objects. - -* ``lj_gc_cdatanum``—number of allocated ``cdata`` objects. - -* ``lj_gc_udatanum``—number of allocated ``udata`` objects. - -* ``lj_gc_freed`` —total amount of freed memory. - -* ``lj_gc_total``—current allocated Lua memory. - -* ``lj_gc_allocated``—total amount of allocated memory. +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``lj_gc_strnum`` + - Number of allocated ``string`` objects + * - ``lj_gc_tabnum`` + - Number of allocated ``table`` objects + * - ``lj_gc_cdatanum`` + - Number of allocated ``cdata`` objects + * - ``lj_gc_udatanum`` + - Number of allocated ``udata`` objects + * - ``lj_gc_freed`` + - Total amount of freed memory + * - ``lj_gc_total`` + - Current allocated Lua memory + * - ``lj_gc_allocated`` + - Total amount of allocated memory .. _metrics-reference-psutils: CPU metrics ----------- -These metrics provide the CPU usage statistics. +The following metrics provide CPU usage statistics. They are only available on Linux. -* ``tnt_cpu_count``—total number of processors configured by the operating system. +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_cpu_count`` + - Total number of processors configured by the operating system + * - ``tnt_cpu_total`` + - Host CPU time + * - ``tnt_cpu_thread`` + - Tarantool thread CPU time. + This metric always has the labels + ``{kind="user", thread_name="tarantool", thread_pid="pid", file_name="init.lua"}``, + where: -* ``tnt_cpu_total``—host CPU time. + * ``kind`` can be either ``user`` or ``system`` + * ``thread_name`` is ``tarantool``, ``wal``, ``iproto``, or ``coio`` + * ``file_name`` is the entrypoint file name, for example, ``init.lua``. -* ``tnt_cpu_thread``—Tarantool thread CPU time. This metric always has labels - ``{kind="user", thread_name="tarantool", thread_pid="pid", file_name="init.lua"}``, - where: +There are also two cross-platform metrics, which can be obtained with a ``getrusage()`` call. - - ``kind`` can be either ``user`` or ``system``. - - ``thread_name`` is ``tarantool``, ``wal``, ``iproto``, or ``coio``. - - ``file_name`` is the entrypoint file name, for example, ``init.lua``. +.. container:: table -There are also the following cross-platform metrics obtained using the call ``getrusage()`` + .. list-table:: + :widths: 25 75 + :header-rows: 0 -* ``tnt_cpu_user_time`` - Tarantool CPU user time. -* ``tnt_cpu_system_time`` - Tarantool CPU system time. + * - ``tnt_cpu_user_time`` + - Tarantool CPU user time + * - ``tnt_cpu_system_time`` + - Tarantool CPU system time .. _metrics-reference-vinyl: Vinyl ----- -Vinyl metrics provide the :ref:`vinyl engine ` statistics. +Vinyl metrics provide :ref:`vinyl engine ` statistics. Disk ~~~~ -The disk metrics are used to monitor the overall data size on disk. +The disk metrics are used to monitor overall data size on disk. -* ``tnt_vinyl_disk_data_size``—the amount of data stored in the ``.run`` files - located in the :ref:`vinyl_dir ` directory, bytes. +.. container:: table -* ``tnt_vinyl_disk_index_size``—the amount of data stored in the ``.index`` files - located in the :ref:`vinyl_dir ` directory, bytes. + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_vinyl_disk_data_size`` + - Amount of data in bytes stored in the ``.run`` files + located in :ref:`vinyl_dir ` + * - ``tnt_vinyl_disk_index_size`` + - Amount of data in bytes stored in the ``.index`` files + located in :ref:`vinyl_dir ` .. _metrics-reference-vinyl_regulator: Regulator ~~~~~~~~~ -The vinyl regulator decides when to take the disk IO actions. -It groups activities in batches so that they will be more consistent and +The vinyl regulator decides when to commence disk IO actions. +It groups activities in batches so that they are more consistent and efficient. -* ``tnt_vinyl_regulator_dump_bandwidth``—the estimated average rate of taking - dumps, bytes per second. Initially, the rate value is 10485760 - (10 megabytes per second) and being recalculated depending on the the actual - rate. Only significant dumps that are larger than one megabyte are used for - the estimate. - -* ``tnt_vinyl_regulator_write_rate``—the actual average rate of performing the - write operations, bytes per second. The rate is calculated as - a 5-second moving average. If the metric value is gradually going down, - this can indicate some disk issues. - -* ``tnt_vinyl_regulator_rate_limit``—the write rate limit, bytes per second. - The regulator imposes the limit on transactions based on the observed - dump/compaction performance. If the metric value is down to approximately - 10^5, this indicates issues with the disk or the :ref:`scheduler `. - -* ``tnt_vinyl_regulator_dump_watermark``—the maximum amount of memory used - for in-memory storing of a vinyl LSM tree, bytes. When accessing this - maximum, the dumping must occur. For details, see :ref:`engines-algorithm_filling_lsm`. - The value is slightly smaller than the amount of memory allocated - for vinyl trees, which is the :ref:`vinyl_memory ` - parameter. +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_vinyl_regulator_dump_bandwidth`` + - Estimated average dumping rate, bytes per second. + The rate value is initially 10485760 (10 megabytes per second). + It is recalculated depending on the the actual rate. + Only significant dumps that are larger than 1 MB are used for estimating. + * - ``tnt_vinyl_regulator_write_rate`` + - Actual average rate of performing write operations, bytes per second. + The rate is calculated as a 5-second moving average. + If the metric value is gradually going down, + this can indicate disk issues. + * - ``tnt_vinyl_regulator_rate_limit`` + - Write rate limit, bytes per second. + The regulator imposes the limit on transactions + based on the observed dump/compaction performance. + If the metric value is down to approximately ``10^5``, + this indicates issues with the disk + or the :ref:`scheduler `. + * - ``tnt_vinyl_regulator_dump_watermark`` + - Maximum amount of memory in bytes used + for in-memory storing of a vinyl LSM tree. + When this maximum is accessed, a dump must occur. + For details, see :ref:`engines-algorithm_filling_lsm`. + The value is slightly smaller + than the amount of memory allocated for vinyl trees, + reflected in the :ref:`vinyl_memory ` parameter. Transactional activity ~~~~~~~~~~~~~~~~~~~~~~ -* ``tnt_vinyl_tx_commit``—the counter of commits (successful transaction ends). - It includes implicit commits: for example, any insert operation causes a - commit unless it is within a - :doc:`/reference/reference_lua/box_txn_management/begin`–:doc:`/reference/reference_lua/box_txn_management/commit` - block. - -* ``tnt_vinyl_tx_rollback``—the counter of rollbacks (unsuccessful transaction - ends). This is not merely a count of explicit :doc:`/reference/reference_lua/box_txn_management/rollback` - requests—it includes requests that ended with errors. - -* ``tnt_vinyl_tx_conflict``—the counter of conflicts that caused transactions - to roll back. The ratio ``tnt_vinyl_tx_conflict / tnt_vinyl_tx_commit`` - above 5% indicates that vinyl is not healthy. At this moment you'll probably - see a lot of other problems with vinyl. - -* ``tnt_vinyl_tx_read_views``—the current number of read views, that is, transactions - entered a read-only state to avoid conflict temporarily. Usually the value - is ``0``. If it stays non-zero for a long time, it indicates of a memory leak. +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_vinyl_tx_commit`` + - Counter of commits (successful transaction ends) + Includes implicit commits: for example, any insert operation causes a + commit unless it is within a + :doc:`/reference/reference_lua/box_txn_management/begin`\ --\ :doc:`/reference/reference_lua/box_txn_management/commit` + block. + * - ``tnt_vinyl_tx_rollback`` + - Сounter of rollbacks (unsuccessful transaction ends). + This is not merely a count of explicit + :doc:`/reference/reference_lua/box_txn_management/rollback` + requests---it includes requests that ended with errors. + * - ``tnt_vinyl_tx_conflict`` + - Counter of conflicts that caused transactions to roll back. + The ratio ``tnt_vinyl_tx_conflict / tnt_vinyl_tx_commit`` + above 5% indicates that vinyl is not healthy. + At that moment, you'll probably see a lot of other problems with vinyl. + * - ``tnt_vinyl_tx_read_views`` + - Current number of read views---that is, transactions + that entered the read-only state to avoid conflict temporarily. + Usually the value is ``0``. + If it stays non-zero for a long time, it is indicative of a memory leak. Memory ~~~~~~ -These metrics show the state memory areas used by vinyl for caches and write -buffers. - -* ``tnt_vinyl_memory_tuple_cache``—the amount of memory that is being used - for storing tuples (data), bytes. - -* ``tnt_vinyl_memory_level0``—the "level 0" (L0) memory area, bytes. - L0 is the area that vinyl can use for in-memory storage of an LSM tree. - By monitoring the metric, you can see when L0 is getting close to its - maximum (``tnt_vinyl_regulator_dump_watermark``) at which a dump will be - taken. You can expect L0 = 0 immediately after the dump operation is - completed. - -* ``tnt_vinyl_memory_page_index``—the amount of memory that is being used - for storing indexes, bytes. If the metric value is close to :ref:`vinyl_memory `, - this indicates the incorrectly chosen :ref:`vinyl_page_size `. - -* ``tnt_vinyl_memory_bloom_filter``—the amount of memory used by - :ref:`bloom filters `, - bytes. +The following metrics show state memory areas used by vinyl for caches and write buffers. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_vinyl_memory_tuple_cache`` + - Amount of memory in bytes currently used to store tuples (data) + * - ``tnt_vinyl_memory_level0`` + - "Level 0" (L0) memory area, bytes. + L0 is the area that vinyl can use for in-memory storage of an LSM tree. + By monitoring this metric, you can see when L0 is getting close to its + maximum (``tnt_vinyl_regulator_dump_watermark``), + at which time a dump will occur. + You can expect L0 = 0 immediately after the dump operation is completed. + * - ``tnt_vinyl_memory_page_index`` + - Amount of memory in bytes currently used to store indexes. + If the metric value is close to :ref:`vinyl_memory `, + this indicates that :ref:`vinyl_page_size ` + was chosen incorrectly. + * - ``tnt_vinyl_memory_bloom_filter`` + - Amount of memory in bytes used by + :ref:`bloom filters `. .. _metrics-reference-vinyl_scheduler: @@ -412,15 +623,22 @@ Scheduler The vinyl scheduler invokes the :ref:`regulator ` and updates the related variables. This happens once per second. -* ``tnt_vinyl_scheduler_tasks``—the number of the scheduler dump/compaction - tasks. The metric always has label ``{status = }`` - where ```` can be: +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 - * ``inprogress`` for currently running tasks - * ``completed`` for successfully completed tasks - * ``failed`` for tasks aborted due to errors. + * - ``tnt_vinyl_scheduler_tasks`` + - Number of scheduler dump/compaction tasks. + The metric always has label ``{status = }``, + where ```` can be one of the following: -* ``tnt_vinyl_scheduler_dump_time``—total time spent by all worker threads - performing dumps, seconds. + * ``inprogress`` for currently running tasks + * ``completed`` for successfully completed tasks + * ``failed`` for tasks aborted due to errors. -* ``tnt_vinyl_scheduler_dump_count``—the counter of dumps completed. + * - ``tnt_vinyl_scheduler_dump_time`` + - Total time in seconds spent by all worker threads performing dumps. + * - ``tnt_vinyl_scheduler_dump_count`` + - Counter of dumps completed. From 3cb2a66f61d950496a5cfb4f2b7dbc4e401e0936 Mon Sep 17 00:00:00 2001 From: patiencedaur Date: Wed, 20 Oct 2021 14:54:41 +0300 Subject: [PATCH 9/9] Minor spelling and grammar fixes --- doc/monitoring/api_reference.rst | 105 +++++++++++++++-------------- doc/monitoring/getting_started.rst | 32 ++++----- doc/monitoring/plugins.rst | 2 +- 3 files changed, 71 insertions(+), 68 deletions(-) diff --git a/doc/monitoring/api_reference.rst b/doc/monitoring/api_reference.rst index 0462d0b1..a7c5056d 100644 --- a/doc/monitoring/api_reference.rst +++ b/doc/monitoring/api_reference.rst @@ -52,7 +52,7 @@ counter .. method:: collect() - :return: Array of ``observation`` objects for the given counter. + :return: Array of ``observation`` objects for a given counter. .. code-block:: lua @@ -100,12 +100,12 @@ gauge .. method:: inc(num, label_pairs) - Works as the ``inc()`` function - of a :ref:`counter `.. + Works like the ``inc()`` function + of a :ref:`counter `. .. method:: dec(num, label_pairs) - Works as ``inc()``, but decrements the observation. + Works like ``inc()``, but decrements the observation. .. method:: set(num, label_pairs) @@ -113,13 +113,13 @@ gauge .. method:: collect() - Returns an array of ``observation`` objects for the given gauge. + Returns an array of ``observation`` objects for a given gauge. For the description of ``observation``, see :ref:`counter_obj:collect() `. .. method:: remove(label_pairs) - Works as the ``remove()`` function + Works like the ``remove()`` function of a :ref:`counter `. .. _metrics-api_reference-histogram: @@ -156,8 +156,8 @@ histogram .. method:: observe(num, label_pairs) Record a new value in a histogram. - This increments all bucket sizes under labels ``le`` >= ``num`` - and labels matching ``label_pairs``. + This increments all bucket sizes under the labels ``le`` >= ``num`` + and the labels that match ``label_pairs``. :param number num: value to put in the histogram. :param table label_pairs: table containing label names as keys, @@ -175,7 +175,7 @@ histogram .. method:: remove(label_pairs) - Works as the ``remove()`` function + Works like the ``remove()`` function of a :ref:`counter `. @@ -186,16 +186,17 @@ summary .. function:: summary(name [, help, objectives]) - Register a new summary. Quantile computation is based on the algorithm + Register a new summary. Quantile computation is based on the `"Effective computation of biased quantiles over data streams" `_ + algorithm. :param string name: сollector name. Must be unique. :param string help: collector description. - :param table objectives: a list of "targeted" φ-quantiles in the form ``{quantile = error, ... }``. - For example: ``{[0.5]=0.01, [0.9]=0.01, [0.99]=0.01}``. - A targeted φ-quantile is specified in the form of a φ-quantile and the tolerated + :param table objectives: a list of "targeted" φ-quantiles in the ``{quantile = error, ... }`` form. + Example: ``{[0.5]=0.01, [0.9]=0.01, [0.99]=0.01}``. + The targeted φ-quantile is specified in the form of a φ-quantile and the tolerated error. For example, ``{[0.5] = 0.1}`` means that the median (= 50th - percentile) must be returned with a 10 percent error. Note that + percentile) is to be returned with a 10-percent error. Note that percentiles and quantiles are the same concept, except that percentiles are expressed as percentages. The φ-quantile must be in the interval ``[0, 1]``. A lower tolerated error for a φ-quantile results in higher memory and CPU @@ -207,7 +208,7 @@ summary (from which observations are collected) is reset, and the next bucket becomes the new head. This way, each bucket stores observations for ``max_age_time * age_buckets_count`` seconds before it is reset. - ``max_age_time`` sets the duration of each bucket lifetime---that is, how + ``max_age_time`` sets the duration of each bucket's lifetime---that is, how many seconds the observations are kept before they are discarded. ``age_buckets_count`` sets the number of buckets in the sliding time window. This variable determines the number of buckets used to exclude observations @@ -222,13 +223,13 @@ summary .. note:: - A summary is basically a set of collectors: + A summary represents a set of collectors: * ``name .. "_sum"``---a counter holding the sum of added observations. * ``name .. "_count"``---a counter holding the number of added observations. - * ``name``---holds all the quantiles under observation that find themselves + * ``name`` holds all the quantiles under observation that find themselves under the label ``quantile`` (less or equal). - To access a specific bucket---``x`` (where ``x`` is a number), + To access bucket ``x`` (where ``x`` is a number), specify the value ``x`` for the label ``quantile``. .. class:: summary_obj @@ -245,7 +246,7 @@ summary You can't add the ``"quantile"`` label to a summary. It is added automatically. If ``max_age_time`` and ``age_buckets_count`` are set, - the observed value will be added to each bucket. + the observed value is added to each bucket. Note that both label names and values in ``label_pairs`` are treated as strings. @@ -255,13 +256,13 @@ summary counters of ``summary_obj``. For the description of ``observation``, see :ref:`counter_obj:collect() `. If ``max_age_time`` and ``age_buckets_count`` are set, quantile observations - will be collected only from the head bucket in the sliding time window - and not from every bucket. If no observations were recorded, - the method will return NaN in the values. + are collected only from the head bucket in the sliding time window, + not from every bucket. If no observations were recorded, + the method will return ``NaN`` in the values. .. method:: remove(label_pairs) - Works as the ``remove()`` function + Works like the ``remove()`` function of a :ref:`counter `. .. _metrics-api_reference-labels: @@ -270,10 +271,10 @@ Labels ------ All collectors support providing ``label_pairs`` on data modification. -Labels are basically pieces of metainfo that you associate with a metric in the format -of key-value pairs. See tags in Graphite and labels in Prometheus. +A label is a piece of metainfo that you associate with a metric in the key-value format. +See tags in Graphite and labels in Prometheus. Labels are used to differentiate between the characteristics of a thing being -measured. For example, in a metric associated with the total number of http +measured. For example, in a metric associated with the total number of HTTP requests, you can represent methods and statuses as label pairs: .. code-block:: lua @@ -283,8 +284,8 @@ requests, you can represent methods and statuses as label pairs: You don't have to predefine labels in advance. With labels, you can extract new time series (visualize their graphs) -by specifying conditions regarding label values. -The example above would allow us to extract the following time series: +by specifying conditions with regard to label values. +The example above allows extracting the following time series: #. The total number of requests over time with ``method = "POST"`` (and any status). #. The total number of requests over time with ``status = 500`` (and any method). @@ -299,13 +300,13 @@ Metrics functions .. function:: enable_default_metrics([include, exclude]) - Enable Tarantool metrics collection. + Enable Tarantool metric collection. :param table include: table containing the names of the default metrics that you need to enable. :param table exclude: table containing the names of the default metrics that you need to exclude. - Default metrics names: + Default metric names: * ``network`` * ``operations`` @@ -332,12 +333,12 @@ Metrics functions :param table label_pairs: table containing label names as string keys, label values as values. - Global labels are applied only to metrics collection. They have no effect + Global labels are applied only to metric collection. They have no effect on how observations are stored. Global labels can be changed on the fly. - ``label_pairs`` from an observation object has priority over global labels. + ``label_pairs`` from observation objects have priority over global labels. If you pass ``label_pairs`` to an observation method with the same key as some global label, the method argument value will be used. @@ -353,7 +354,7 @@ Metrics functions Remove a collector from the registry. - :param collector_obj collector: collector that has to be removed + :param collector_obj collector: the collector to be removed. **Example:** @@ -369,8 +370,8 @@ Metrics functions Find a collector in the registry. - :param string kind: collector kind (``counter``, ``gauge``, ``histogram``, or ``summary``) - :param string name: collector name + :param string kind: collector kind (``counter``, ``gauge``, ``histogram``, or ``summary``). + :param string name: collector name. :return: A collector object or ``nil``. @@ -386,7 +387,7 @@ Metrics functions .. function:: register_callback(callback) - Register a function named ``callback``, which will be called right before metrics + Register a function named ``callback``, which will be called right before metric collection on plugin export. :param function callback: a function that takes no parameters. @@ -404,7 +405,7 @@ Metrics functions .. function:: unregister_callback(callback) - Unregister a function named ``callback`` that is called right before metrics + Unregister a function named ``callback`` that is called right before metric collection on plugin export. :param function callback: a function that takes no parameters. @@ -440,7 +441,7 @@ with ``metrics = require('cartridge.roles.metrics')`` specified in your ``init.l .. function:: set_export(export) - :param table export: table containing the path and format of the exported metrics. + :param table export: a table containing paths and formats of the exported metrics. Configure the endpoints of the metrics role: @@ -463,7 +464,7 @@ with ``metrics = require('cartridge.roles.metrics')`` specified in your ``init.l }) You can add several entry points of the same format but with different paths, - like this: + for example: .. code-block:: lua @@ -517,7 +518,7 @@ latency statistics. .. function:: build_default_collector(type_name, name [, help]) - Register a collector for the middleware and return it. + Register and return a collector for the middleware. :param string type_name: collector type: ``histogram`` or ``summary``. The default is ``histogram``. :param string name: collector name. The default is ``http_server_request_latency``. @@ -538,19 +539,19 @@ latency statistics. .. function:: get_default_collector() Return the default collector. - If the default collector hasn't been set yet, registers it (with default - ``http_middleware.build_default_collector(...)`` parameters) and sets it + If the default collector hasn't been set yet, register it (with default + ``http_middleware.build_default_collector(...)`` parameters) and set it as default. :return: A collector object. .. function:: v1(handler, collector) - Latency measuring wrap-up for HTTP ver. 1.x.x handler. Returns a wrapped handler. + Latency measuring wrap-up for the HTTP ver. 1.x.x handler. Returns a wrapped handler. - :param function handler: Handler function. - :param collector: Middleware collector object. - If not set, uses the default collector + :param function handler: handler function. + :param collector: middleware collector object. + If not set, the default collector is used (like in ``http_middleware.get_default_collector()``). **Usage:** ``httpd:route(route, http_middleware.v1(request_handler, collector))`` @@ -562,7 +563,7 @@ latency statistics. Return the latency measuring middleware for HTTP ver. 2.x.x. :param collector: Middleware collector object. - If not set, uses the default collector + If not set, the default collector is used (like in ``http_middleware.get_default_collector()``). **Usage:** @@ -581,7 +582,9 @@ CPU usage metrics ----------------- CPU metrics work only on Linux. See the :ref:`metrics reference ` -for details. To enable CPU metrics, first register a callback function: +for details. + +To enable CPU metrics, first register a callback function: .. code-block:: lua @@ -620,7 +623,7 @@ for details. To enable CPU metrics, first register a callback function: Examples -------- -Below are some examples of using metrics primitives. +Below are some examples of using metric primitives. Notice that this usage is independent of export plugins such as Prometheus, Graphite, etc. For documentation on how to use the plugins, see @@ -648,7 +651,7 @@ the :ref:`Metrics plugins ` section. local cpu_usage_gauge = metrics.gauge('cpu_usage', 'CPU usage') -- register a lazy gauge value update - -- this will be called whenever the export is invoked in any plugins + -- this will be called whenever export is invoked in any plugins metrics.register_callback(function() local current_cpu_usage = some_cpu_collect_function() cpu_usage_gauge:set(current_cpu_usage, {app = 'tarantool'}) @@ -680,7 +683,7 @@ the :ref:`Metrics plugins ` section. local metrics = require('metrics') local fiber = require('fiber') - -- create a summary with a window of 5 age buckets and 60s bucket lifetime + -- create a summary with a window of 5 age buckets and a bucket lifetime of 60 s local http_requests_latency = metrics.summary( 'http_requests_latency', 'HTTP requests total', {[0.5]=0.01, [0.9]=0.01, [0.99]=0.01}, diff --git a/doc/monitoring/getting_started.rst b/doc/monitoring/getting_started.rst index a3ae5a20..5378c3d9 100644 --- a/doc/monitoring/getting_started.rst +++ b/doc/monitoring/getting_started.rst @@ -111,9 +111,9 @@ Instance health check --------------------- In production environments, Tarantool Cartridge usually has a large number of so-called -routers, Tarantool instances that handle input load. +routers---Tarantool instances that handle input load. Various load balancers help distribute that load evenly. -However, any load balancer has to "know" +However, any load balancer has to know which routers are ready to accept the load at the moment. The Tarantool metrics library has a special plugin that creates an HTTP handler, which the load balancer can use to check the current state of any Tarantool instance. @@ -127,12 +127,12 @@ Cartridge role ``cartridge.roles.metrics`` is a `Tarantool Cartridge `__ role. -It allows using default metrics in a Cartridge application and manage them +It allows using default metrics in a Cartridge application and managing them via Cartridge configuration. **Usage** -#. Add the ``metrics`` package to dependencies in the ``.rockspec`` file. +#. Add the ``metrics`` package to the dependencies in the ``.rockspec`` file. Make sure that you are using version **0.3.0** or higher. .. code-block:: lua @@ -163,7 +163,7 @@ via Cartridge configuration. .. note:: ``set_export`` has lower priority than clusterwide configuration - and can be overridden by the metrics configuration. + and may be overridden by the metrics configuration. .. code-block:: lua @@ -210,22 +210,22 @@ via Cartridge configuration. Since version **0.6.0**, the metrics role is permanent and enabled on instances by default. #. After the role has been initialized, the default metrics will be enabled - and the global label ``'alias'`` will be set. - **Note** that the ``'alias'`` label value is set by the ``alias`` or ``instance_name`` + and the global label ``alias`` will be set. + **Note** that the ``alias`` label value is set by the ``alias`` or ``instance_name`` instance :ref:`configuration option ` (since **0.6.1**). - To use the functionality of any - metrics package, you can get it as a Cartridge service and use it like - a regular package after ``require``: + You can use the functionality of any + metrics package by getting it as a Cartridge service + and calling it with ``require`` like a regular package: .. code-block:: lua local cartridge = require('cartridge') local metrics = cartridge.service_get('metrics') -#. Since Tarantool Cartridge ``'2.4.0'``, you can set a zone for each +#. Since Tarantool Cartridge ``2.4.0``, you can set a zone for each instance in the cluster. When a zone is set, all the metrics on the instance - receive the ``'zone'`` label. + receive the ``zone`` label. #. To change the HTTP path for a metric in **runtime**, you can use the configuration below. @@ -246,7 +246,7 @@ via Cartridge configuration. .. image:: images/role-config.png :align: center -#. To set custom global labels, you can use the following configuration: +#. You can set custom global labels with the following configuration: .. code-block:: yaml @@ -264,7 +264,7 @@ via Cartridge configuration. local metrics = require('cartridge.roles.metrics') metrics.set_default_labels({ ['my-custom-label'] = 'label-value' }) -#. To choose the default metrics to be exported, you can use the configuration below. +#. You can use the configuration below to choose the default metrics to be exported. If you add the include section, only the metrics from this section will be exported: .. code-block:: yaml @@ -279,7 +279,7 @@ via Cartridge configuration. - luajit - memory - When you add the exclude section, + If you add the exclude section, the metrics from this section will be removed from the default metrics list: .. code-block:: yaml @@ -294,5 +294,5 @@ via Cartridge configuration. - luajit - memory - For the full list of default metrics, refer to the + For the full list of default metrics, check the :ref:`API reference `. diff --git a/doc/monitoring/plugins.rst b/doc/monitoring/plugins.rst index ec4fd607..2320c3c7 100644 --- a/doc/monitoring/plugins.rst +++ b/doc/monitoring/plugins.rst @@ -229,7 +229,7 @@ Use the JSON plugin with Tarantool ``http.server`` as follows: Plugin-specific API ------------------- -We encourage you to use the following methods **only when you're developing a new plugin**. +Use the following methods **only when developing a new plugin**. .. module:: metrics