Added docs and unregister callback function

Author: yngvar-antonsson

CHANGELOG.md

@@ -19,6 +19,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - `tnt_clock_delta` metric to compute clock difference on instances
 - set custom global labels in config and with `set_labels` function [#259](https://github.com/tarantool/metrics/issues/259)
+- allow to include and exclude default metrics in config and in `enable_default_metrics` function
+  [#222](https://github.com/tarantool/metrics/issues/222)
+
+### Deprecated
+- `enable_cartridge_metrics` function
 
 ## [0.9.0] - 2021-05-28
 ### Fixed

cartridge/roles/metrics.lua

@@ -157,9 +157,7 @@ local function apply_config(conf)
         end
     end
     apply_routes(paths)
-    metrics.clear()
     metrics.enable_default_metrics(metrics_conf.include, metrics_conf.exclude)
-    metrics.enable_cartridge_metrics()
     set_labels(metrics_conf['global-labels'])
 end
 
@@ -194,7 +192,6 @@ end
 local function init()
     set_labels(metrics_vars.custom_labels)
     metrics.enable_default_metrics()
-    metrics.enable_cartridge_metrics()
     local current_paths = table.copy(metrics_vars.config)
     for path, format in pairs(metrics_vars.default) do
         if current_paths[path] == nil then

doc/monitoring/api_reference.rst

@@ -266,15 +266,33 @@ You can also set global labels by calling
 Metrics functions
 -------------------------------------------------------------------------------
 
-..  function:: enable_default_metrics()
+..  function:: enable_default_metrics(include, exclude)
 
-    Enables Tarantool metrics collections. See :ref:`metrics reference <metrics-reference>`
-    for details.
+    Enables Tarantool metrics collections.
 
-..  function:: enable_cartridge_metrics()
+    :param table include: Table containing names of default metrics which you need to enable.
 
-    Enables Cartridge metrics collections. See :ref:`metrics reference <metrics-cartridge>`
-    for details.
+    :param table exclude: Table containing names of default metrics which you need to exclude.
+
+    Default metrics names:
+
+    * "network"
+    * "operations"
+    * "system"
+    * "replicas"
+    * "info"
+    * "slab"
+    * "runtime"
+    * "memory"
+    * "spaces"
+    * "fibers"
+    * "cpu"
+    * "vinyl"
+    * "luajit"
+    * "cartridge_issues"
+    * "clock"
+
+    See :ref:`metrics reference <metrics-reference>` for details.
 
 ..  function:: metrics.set_global_labels(label_pairs)
 
@@ -301,6 +319,15 @@ Metrics functions
 
     Most common usage is for gauge metrics updates.
 
+..  function:: unregister_callback(callback)
+
+    Unregisters a function ``callback`` which will be called right before metrics
+    collection on plugin export.
+
+    :param function callback: Function which takes no parameters.
+
+    Most common usage is for unregister enabled callbacks.
+
 .. _collecting-http-statistics:
 
 -------------------------------------------------------------------------------

doc/monitoring/getting_started.rst

@@ -217,4 +217,36 @@ via configuration.
    ..  code-block:: lua
 
        local metrics = require('cartridge.roles.metrics')
-       metrics.set_labels({ ['my-custom-label'] = 'label-value'} )
+       metrics.set_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:
+
+   ..  code-block:: yaml
+
+       metrics:
+         export:
+         - path: '/metrics'
+           format: 'json'
+         # export all metrics except vinyl, luajit and memory:
+         exclude:
+         - vinyl
+         - luajit
+         - memory
+
+   You can see list of defaul metrics in :ref:`API reference <metrics-functions>`.

metrics/default_metrics/tarantool/init.lua

@@ -14,22 +14,38 @@ local default_metrics = {
     cpu = require('metrics.default_metrics.tarantool.cpu'),
     vinyl = require('metrics.tarantool.vinyl'),
     luajit = require('metrics.tarantool.luajit'),
+    cartridge_issues = require('metrics.cartridge.issues'),
+    clock = require('metrics.cartridge.clock'),
 }
 
 local function enable(include, exclude)
+    include = include or {}
+    exclude = exclude or {}
+
     local exclude_map = {}
-    for _, name in ipairs(exclude or {}) do
+    for _, name in ipairs(exclude) do
         exclude_map[name] = true
     end
-    if include then
-        for _, name in ipairs(include) do
-            metrics.register_callback(default_metrics[name].update)
-        end
-    else
-        for name, metric in pairs(default_metrics) do
-            if not exclude_map[name] then
-                metrics.register_callback(metric.update)
+    local include_map = {}
+    for _, name in ipairs(include) do
+        include_map[name] = true
+    end
+
+    for name, value in pairs(default_metrics) do
+        if #include > 0 then
+            if include_map[name] ~= nil then
+                metrics.register_callback(value.update)
+            else
+                metrics.unregister_callback(value.update)
+            end
+        elseif #exclude > 0 then
+            if exclude_map[name] ~= nil then
+                metrics.unregister_callback(value.update)
+            else
+                metrics.register_callback(value.update)
             end
+        else
+            metrics.register_callback(value.update)
         end
     end
 end

metrics/init.lua

@@ -1,6 +1,7 @@
 -- vim: ts=4:sw=4:sts=4:expandtab
 
 local checks = require('checks')
+local log = require('log')
 
 local Registry = require('metrics.registry')
 
@@ -23,6 +24,10 @@ local function register_callback(...)
     return registry:register_callback(...)
 end
 
+local function unregister_callback(...)
+    return registry:unregister_callback(...)
+end
+
 local function invoke_callbacks()
     return registry:invoke_callbacks()
 end
@@ -109,12 +114,14 @@ return {
     clear = clear,
     collectors = collectors,
     register_callback = register_callback,
+    unregister_callback = unregister_callback,
     invoke_callbacks = invoke_callbacks,
     set_global_labels = set_global_labels,
     enable_default_metrics = function(include, exclude)
         require('metrics.default_metrics.tarantool').enable(include, exclude)
     end,
     enable_cartridge_metrics = function()
+        log.warn('metrics.enable_cartridge_metrics() is deprecated. Use metrics.enable_default_metrics() instead.')
         return require('metrics.cartridge').enable()
     end,
     http_middleware = require('metrics.http_middleware'),

metrics/registry.lua

@@ -70,6 +70,14 @@ function Registry:register_callback(callback)
     end
 end
 
+function Registry:unregister_callback(callback)
+    for i, registered_callback in ipairs(self.callbacks) do
+        if registered_callback == callback then
+            table.remove(self.callbacks, i)
+        end
+    end
+end
+
 function Registry:set_labels(label_pairs)
     self.label_pairs = table.copy(label_pairs)
 end