From c7822f32d9e30bd3ea1907759dcdd500565098af Mon Sep 17 00:00:00 2001 From: Igor Zolotarev Date: Thu, 28 Jan 2021 20:27:57 +0300 Subject: [PATCH 1/3] docs: set_export documentation --- README.md | 23 +++++++++ doc/monitoring/getting_started.rst | 65 ++++++++++++------------ test/integration/cartridge_role_test.lua | 15 ++++++ 3 files changed, 70 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 01ba9030..11fec071 100644 --- a/README.md +++ b/README.md @@ -186,7 +186,30 @@ via configuration. - path: '/health' format: 'health' ``` + **OR** + Use `set_export`: + + **NOTE** that `set_export` has lower priority than clusterwide config and won't work if metrics config is present. + + ```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: ```yaml metrics: diff --git a/doc/monitoring/getting_started.rst b/doc/monitoring/getting_started.rst index 92b56bce..c4a6b316 100644 --- a/doc/monitoring/getting_started.rst +++ b/doc/monitoring/getting_started.rst @@ -70,12 +70,12 @@ 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, +"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. .. _cartridge-role: @@ -117,6 +117,31 @@ via configuration. }, }) +#. To view metrics via API endpoints, use ``set_export``: + + **NOTE** that ``set_export`` has lower priority than clusterwide config and won't work if metrics config is present. + + .. 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' + } + }) + + 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 @@ -137,7 +162,7 @@ via configuration. local cartridge = require('cartridge') local metrics = cartridge.service_get('metrics') -#. To view metrics via API endpoints, use the following configuration +#. To change metrics HTTP path, use the following configuration (to learn more about Cartridge configuration, see `this `_): @@ -155,32 +180,6 @@ via configuration. .. image:: images/role-config.png :align: center - **OR** - - Use ``set_export``: - - **NOTE** that ``set_export`` has lower priority than clusterwide config and won't work if metrics config is present. - - .. code-block:: lua - - metrics.set_export({ - { - path = '/path_for_json_metrics', - format = 'json' - }, - { - path = '/path_for_prometheus_metrics', - format = 'prometheus' - }, - { - path = '/health', - format = 'health' - } - }) - - The metrics will be available on the path specified in ``path`` in the format - specified in ``format``. - You can add several entry points of the same format by different paths, like this: diff --git a/test/integration/cartridge_role_test.lua b/test/integration/cartridge_role_test.lua index 8a082a06..a8c22778 100644 --- a/test/integration/cartridge_role_test.lua +++ b/test/integration/cartridge_role_test.lua @@ -274,3 +274,18 @@ g.test_non_empty_clusterwide_config_overrides_set_export = function() resp = server:http_request('get', '/new-metrics', {raise = false}) t.assert_equals(resp.status, 404) end + +g.test_set_export_from_require_role = function() + local server = g.cluster.main_server + server.net_box:eval([[ + local metrics = require('cartridge.roles.metrics') + metrics.set_export(...) + ]], {{ + { + path = '/metrics', + format = 'json', + }, + }}) + local resp = server:http_request('get', '/metrics', {raise = false}) + t.assert_equals(resp.status, 200) +end From 53867546e745e198fcb19acc370d08125221b0a0 Mon Sep 17 00:00:00 2001 From: Igor Zolotarev Date: Tue, 2 Feb 2021 20:10:59 +0300 Subject: [PATCH 2/3] config is optional --- doc/monitoring/getting_started.rst | 33 ++++++++++++++++++------------ 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/doc/monitoring/getting_started.rst b/doc/monitoring/getting_started.rst index c4a6b316..0331af79 100644 --- a/doc/monitoring/getting_started.rst +++ b/doc/monitoring/getting_started.rst @@ -139,6 +139,22 @@ via configuration. } }) + You can add several entry points of the same format by different paths, + like this: + + .. code-block:: yaml + + 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``. @@ -162,9 +178,10 @@ via configuration. local cartridge = require('cartridge') local metrics = cartridge.service_get('metrics') -#. To change metrics HTTP path, use the following configuration +#. To change metrics HTTP path in **runtime**, you may use the following configuration (to learn more about Cartridge configuration, see - `this `_): + `this `_). + We don't recommend to use it to set up metrics role, use ``set_export`` instead. .. code-block:: yaml @@ -180,14 +197,4 @@ via configuration. .. image:: images/role-config.png :align: center - You can add several entry points of the same format by different paths, - like this: - - .. code-block:: yaml - - metrics: - export: - - path: '/path_for_json_metrics' - format: 'json' - - path: '/another_path_for_json_metrics' - format: 'json' +.. _grafana-dashboard: From 4b9947c1a3a4676faf785d275b3d3f658bbd46b8 Mon Sep 17 00:00:00 2001 From: Igor Zolotarev Date: Wed, 3 Feb 2021 15:15:04 +0300 Subject: [PATCH 3/3] README --- README.md | 88 ++++++++++++++---------------- doc/monitoring/getting_started.rst | 3 +- 2 files changed, 41 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 11fec071..cde8c9d8 100644 --- a/README.md +++ b/README.md @@ -164,61 +164,53 @@ via configuration. }, }) ``` -3. After role initialization, default metrics will be enabled and the global - label 'alias' will be set. 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`: + +3. To view metrics via API endpoints, use `set_export`. + **NOTE** that `set_export` has lower priority than clusterwide config and won't work if metrics config is present. + ```lua - local cartridge = require('cartridge') - local metrics = cartridge.service_get('metrics') + 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: -4. To view metrics via API endpoints, use the following configuration - (to learn more about Cartridge configuration, see - [this](https://www.tarantool.io/en/doc/latest/book/cartridge/topics/clusterwide-config/#managing-role-specific-data)): - ```yaml - metrics: - export: - - path: '/path_for_json_metrics' - format: 'json' - - path: '/path_for_prometheus_metrics' - format: 'prometheus' - - path: '/health' - format: 'health' + ```lua + metrics.set_export({ + { + path = '/path_for_json_metrics', + format = 'json' + }, + { + path = '/another_path_for_json_metrics', + format = 'json' + }, + }) ``` - **OR** - - Use `set_export`: - - **NOTE** that `set_export` has lower priority than clusterwide config and won't work if metrics config is present. + The metrics will be available on the path specified in `path` in the format + specified in `format`. +4. After role initialization, default metrics will be enabled and the global + label 'alias' will be set. 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`: ```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' - } - }) + local cartridge = require('cartridge') + local metrics = cartridge.service_get('metrics') ``` -You can add several entry points of the same format by different paths, like this: -```yaml -metrics: - export: - - path: '/path_for_json_metrics' - format: 'json' - - path: '/another_path_for_json_metrics' - format: 'json' -``` ## Next steps diff --git a/doc/monitoring/getting_started.rst b/doc/monitoring/getting_started.rst index 0331af79..77ddf6c5 100644 --- a/doc/monitoring/getting_started.rst +++ b/doc/monitoring/getting_started.rst @@ -117,7 +117,7 @@ via configuration. }, }) -#. To view metrics via API endpoints, use ``set_export``: +#. To view metrics via API endpoints, use ``set_export``. **NOTE** that ``set_export`` has lower priority than clusterwide config and won't work if metrics config is present. @@ -197,4 +197,3 @@ via configuration. .. image:: images/role-config.png :align: center -.. _grafana-dashboard: