api: add metrics support

The patch adds the ability to export statistics to metrics >= 0.10.0.
expirationd does not require the metrics package itself and tries to
use an installed one.

It also adds a new API method expirationd.cfg({options}).

Part of #100

Author: oleg-jukovec

expirationd.lua

@@ -10,6 +10,7 @@ local checks = require("checks")
 local fun = require("fun")
 local log = require("log")
 local fiber = require("fiber")
+local is_metrics_package, metrics = pcall(require, "metrics")
 
 -- get fiber id function
 local function get_fiber_id(fiber)
@@ -21,6 +22,7 @@ local function get_fiber_id(fiber)
 end
 
 local task_list = {}
+local cfg = {metrics = true}
 
 local constants = {
     -- default value of number of tuples that will be checked by one iteration
@@ -49,6 +51,79 @@ local constants = {
     atomic_iteration = false,
 }
 
+local metrics_callback = nil
+local metrics_collectors = nil
+
+local function metrics_enable()
+    if metrics_callback then
+        return
+    end
+
+    local supported_v0_11 = false
+    if is_metrics_package and metrics.unregister_callback then
+        local counter = require('metrics.collectors.counter')
+        supported_v0_11 = counter.remove and true or false
+    end
+    if not supported_v0_11 then
+        error("metrics >= 0.11.0 is required", 3)
+    end
+
+    local create_collector = function(name, description)
+        return {
+            collector = metrics.counter(name, description),
+            task_value = {},
+        }
+    end
+
+    metrics_collectors = {
+        ["checked_count"] = create_collector(
+            "expirationd_checked_count",
+            "expirationd task's a number of checked tuples"
+        ),
+        ["expired_count"] = create_collector(
+            "expirationd_expired_count",
+            "expirationd task's a number of expired tuples"
+        ),
+        ["restarts"] = create_collector(
+            "expirationd_restarts",
+            "expirationd task's a number of restarts"
+        ),
+        ["working_time"] = create_collector(
+            "expirationd_working_time",
+            "expirationd task's operation time"
+        ),
+    }
+
+    metrics_callback = function()
+        for task_name, task in pairs(task_list) do
+            local stats = task:statistics()
+            for k, v in pairs(stats) do
+                local prev_v = metrics_collectors[k].task_value[task_name] or 0
+                local v_inc = v - prev_v
+                metrics_collectors[k].collector:inc(v_inc, {name = task_name})
+                metrics_collectors[k].task_value[task_name] = v
+            end
+        end
+    end
+    metrics.register_callback(metrics_callback)
+end
+
+if cfg.metrics then
+    enabled, _ = pcall(metrics_enable)
+    cfg.metrics = enabled
+end
+
+local function metrics_disable()
+    if metrics_callback then
+        for _, c in pairs(metrics_collectors) do
+            metrics.registry:unregister(c.collector)
+        end
+        metrics.unregister_callback(metrics_callback)
+        metrics_callback = nil
+        metrics_collectors = nil
+    end
+end
+
 -- ========================================================================= --
 -- Task local functions
 -- ========================================================================= --
@@ -281,6 +356,12 @@ local Task_methods = {
     -- @function task.kill
     kill = function (self)
         self:stop()
+        if metrics_collectors then
+            for _, c in pairs(metrics_collectors) do
+                c.collector:remove({name = self.name})
+                c.task_value[self.name] = nil
+            end
+        end
         task_list[self.name] = nil
     end,
 
@@ -400,6 +481,63 @@ end
 --
 -- @section Functions
 
+--- Configure expirationd.
+--
+-- How to set up a configuration option:
+--
+-- ```
+-- expirationd.cfg({metrics = true})
+-- ```
+--
+-- How to get an option value:
+--
+-- ```
+-- print(expirationd.cfg.metrics)
+-- true
+-- ```
+--
+-- @table options
+--
+-- @bool[opt] options.metrics
+--     Enable or disable stats collection by [metrics][1]. metrics >= 0.11.0
+--     is required. It is enabled by default.
+--
+--     If enabled it creates four counter collectors, see @{task.statistics}:
+--
+--     1. `expirationd_checked_count`
+--
+--     2. `expirationd_expired_count`
+--
+--     3. `expirationd_restarts`
+--
+--     4. `expirationd_working_time`
+--
+--     Labeled with `name = task_name`.
+--
+--     [1]: https://github.com/tarantool/metrics/
+--
+-- @return None
+--
+-- @function expirationd.cfg
+local function expirationd_cfg(self, options)
+    checks('table', {
+        metrics = '?boolean',
+    })
+
+    if options.metrics == nil then
+        return
+    end
+
+    if cfg.metrics ~= options.metrics then
+        if options.metrics == true then
+            metrics_enable()
+        else
+            metrics_disable()
+        end
+        rawset(cfg, 'metrics', options.metrics)
+    end
+end
+
 --- Run a scheduled task to check and process (expire) tuples in a given space.
 --
 -- How expirationd works in general:
@@ -949,6 +1087,12 @@ local function show_task_list_obsolete(...)
 end
 
 return {
+    cfg     = setmetatable({}, {
+        __index = cfg,
+        __newindex = function() error("Use expirationd.cfg{} instead", 2) end,
+        __call = expirationd_cfg,
+        __serialize = function() return cfg end,
+    }),
     start   = expirationd_run_task,
     stats   = expirationd_task_stats,
     update  = expirationd_update,

test/helper.lua

@@ -223,6 +223,16 @@ function helpers.is_expired_true()
     return true
 end
 
+function helpers.is_metrics_supported()
+    local is_package, metrics = pcall(require, "metrics")
+    if not is_package then
+        return false
+    end
+    -- metrics >= 0.11.0 is required
+    local counter = require('metrics.collectors.counter')
+    return metrics.unregister_callback and counter.remove
+end
+
 function helpers.iterate_with_func(task)
     return task.index:pairs(task.start_key(), { iterator = task.iterator_type })
        :take_while(

test/unit/cfg_test.lua

@@ -0,0 +1,51 @@
+local expirationd = require("expirationd")
+local t = require("luatest")
+local helpers = require("test.helper")
+local g = t.group('expirationd_cfg')
+
+function g.test_cfg_default_if_installed()
+    t.skip_if(not helpers.is_metrics_supported(), "metrics is not installed")
+    t.assert_equals(expirationd.cfg.metrics, true)
+end
+
+function g.test_cfg_default_if_uninstalled()
+    t.skip_if(helpers.is_metrics_supported(), "metrics is installed")
+    t.assert_equals(expirationd.cfg.metrics, false)
+end
+
+function g.test_cfg_newindex()
+    t.assert_error_msg_content_equals("Use expirationd.cfg{} instead",
+                                      function()
+                                          expirationd.cfg.any_key = false
+                                      end)
+end
+
+function g.test_cfg_metrics_set_unset()
+    t.skip_if(not helpers.is_metrics_supported(), "metrics is not installed")
+
+    expirationd.cfg({metrics = true})
+    t.assert_equals(expirationd.cfg.metrics, true)
+    expirationd.cfg({metrics = false})
+    t.assert_equals(expirationd.cfg.metrics, false)
+end
+
+function g.test_cfg_metrics_multiple_set_unset()
+    t.skip_if(not helpers.is_metrics_supported(), "metrics is not installed")
+
+    expirationd.cfg({metrics = true})
+    expirationd.cfg({metrics = true})
+    t.assert_equals(expirationd.cfg.metrics, true)
+    expirationd.cfg({metrics = false})
+    expirationd.cfg({metrics = false})
+    t.assert_equals(expirationd.cfg.metrics, false)
+end
+
+function g.test_cfg_metrics_set_unsupported()
+    t.skip_if(helpers.is_metrics_supported(), "metrics is installed")
+
+    t.assert_error_msg_content_equals("metrics >= 0.11.0 is required",
+                                      function()
+                                          expirationd.cfg({metrics = true})
+                                      end)
+    t.assert_equals(expirationd.cfg.metrics, false)
+end