Metrics docs

Author: andreyaksenov

doc/book/admin/index.rst

@@ -41,3 +41,4 @@ This chapter includes the following sections:
    os_notes
    bug_reports
    troubleshoot
+   monitoring

doc/book/admin/monitoring.rst

@@ -0,0 +1,17 @@
+..  _monitoring:
+
+Monitoring
+==========
+
+Monitoring is the process of measuring and tracking Tarantool performance based on metrics.
+The metrics are typically monitored in real time, which allows you to identify or predict issues.
+
+..  toctree::
+    :maxdepth: 1
+    :numbered: 0
+
+    monitoring/getting_started
+    monitoring/plugins
+    monitoring/grafana_dashboard
+    monitoring/alerting
+    monitoring/metrics_reference

doc/book/admin/monitoring/alerting.rst

@@ -0,0 +1,200 @@
+..  _monitoring-getting_started:
+
+Getting started with monitoring
+===============================
+
+..  NOTE::
+
+    If you use Tarantool version below `2.11.1 <https://github.com/tarantool/tarantool/releases/tag/2.11.1>`__,
+    it is necessary to install the latest version of `metrics <https://github.com/tarantool/metrics>`__ first.
+
+Main concepts:
+
+-   overview
+-   metrics configuration
+-   metrics module
+
+
+.. _monitoring_overview:
+
+Overview
+--------
+
+-   collectors
+-   built-in metrics
+-   metrics of third-party plugins (crud, expirationd)
+-   custom metrics
+
+
+.. _monitoring_quick_start:
+
+Quick start
+-----------
+
+Example on GitHub: `metrics <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/metrics>`_
+
+
+1.  Config (``config.yaml``) -- the :ref:`metrics <configuration_reference_metrics>` section:
+
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/metrics/config.yaml
+        :end-before: roles:
+        :language: yaml
+        :dedent:
+
+2.  Serve metrics using a :ref:`role <application_roles>` -- config:
+
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/metrics/config.yaml
+        :start-at: roles:
+        :end-at: expose_prometheus_metrics
+        :language: yaml
+        :dedent:
+
+3.  Create ``expose_prometheus_metrics.lua`` in the ``examples`` directory next to the ``config.yaml`` file:
+
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/metrics/examples/expose_prometheus_metrics.lua
+        :language: lua
+        :dedent:
+
+4.  Install the `http <https://github.com/tarantool/http>`__ external module:
+
+    ..  code-block:: console
+
+        $ tt rocks install http
+
+5.  Start app:
+
+    ..  code-block:: console
+
+        $ tt start metrics
+
+    Access metrics `http://127.0.0.1:8080/metrics/prometheus <http://127.0.0.1:8080/metrics/prometheus>`_.
+
+6.  Prometheus scrape config (``prometheus.yml``):
+
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/metrics/prometheus.yml
+        :language: yaml
+        :dedent:
+
+
+
+
+
+.. _monitoring_configuring_metrics:
+
+Configuring metrics
+-------------------
+
+Example 1 (built-in)
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/metrics/config.yaml
+    :end-before: roles:
+    :language: yaml
+    :dedent:
+
+
+Example 2 (third-party)
+
+The example below shows how to enable statistics on called operations by providing the ``roles.crud-router`` role's configuration:
+
+..  literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml
+    :language: yaml
+    :start-at: roles.crud-router
+    :end-at: stats_quantile_max_age_time
+    :dedent:
+
+Example on GitHub: `sharded_cluster_crud <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud>`_
+
+
+
+.. _monitoring_using_metrics_module:
+
+Using the 'metrics' module
+--------------------------
+
+.. _metrics-plugins-available:
+.. _monitoring_plugins_for_exposing_metrics:
+
+Plugins for exposing metrics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Prometheus (:ref:`metrics-prometheus-api_reference`):
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/metrics/examples/expose_prometheus_metrics.lua
+    :start-at: local prometheus_plugin
+    :end-at: local prometheus_metrics
+    :language: lua
+    :dedent:
+
+JSON (:ref:`metrics-json-api_reference`):
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/metrics/examples/expose_json_metrics.lua
+    :start-at: local json_plugin
+    :end-at: local json_metrics
+    :language: lua
+    :dedent:
+
+Graphite (:ref:`metrics-graphite-api_reference`):
+
+..  code-block:: lua
+
+    local graphite_plugin = require('metrics.plugins.graphite')
+    graphite_plugin.init {
+        prefix = 'tarantool',
+        host = '127.0.0.1',
+        port = 2003,
+        send_interval = 1,
+    }
+
+
+..  NOTE::
+
+    Custom plugins note.
+
+
+
+.. _monitoring_metrics_collecting:
+
+Collecting metrics
+~~~~~~~~~~~~~~~~~~
+
+TODO
+
+
+.. _monitoring_metrics_collecting_http:
+
+Collecting HTTP metrics
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Example:
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/metrics/examples/collect_http_metrics.lua
+    :start-after: Collect HTTP metrics
+    :end-at: httpd:start()
+    :language: lua
+    :dedent:
+
+
+
+.. _monitoring_metrics_collecting_custom_metrics:
+
+Collecting custom metrics
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Example 1:
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/metrics/examples/collect_custom_replace_count.lua
+    :start-after: Collect a custom metric
+    :end-before: -- End --
+    :language: lua
+    :dedent:
+
+
+Example 2:
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/metrics/examples/collect_custom_waste_size.lua
+    :start-after: Collect a custom metric
+    :end-before: -- End --
+    :language: lua
+    :dedent:
+
+