diff --git a/README.md b/README.md index 01ba9030..cde8c9d8 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,46 @@ via configuration. }, }) ``` -3. After role initialization, default metrics will be enabled and the global + +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 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: + + ```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`. + +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`: @@ -173,30 +212,6 @@ via configuration. local metrics = cartridge.service_get('metrics') ``` -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' - ``` - -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 See: diff --git a/doc/monitoring/getting_started.rst b/doc/monitoring/getting_started.rst index 92b56bce..77ddf6c5 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,47 @@ 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' + } + }) + + 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``. + #. Enable role in the interface: .. image:: images/role-enable.png @@ -137,9 +178,10 @@ 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 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 @@ -155,40 +197,3 @@ 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: - - .. code-block:: yaml - - metrics: - export: - - path: '/path_for_json_metrics' - format: 'json' - - path: '/another_path_for_json_metrics' - format: 'json' 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