docs: set_export documentation (#180)

Author: yngvar-antonsson

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:

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 <https://www.tarantool.io/en/doc/latest/book/cartridge/topics/clusterwide-config/#managing-role-specific-data>`_):
+   `this <https://www.tarantool.io/en/doc/latest/book/cartridge/topics/clusterwide-config/#managing-role-specific-data>`_).
+   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'

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