stats: make quantile age params configurable

The main motivation of making these parameters configurable is to be
able to write time-adequate test cases for #286 issue, but they may be
useful in getting rid of #286 effect at all or in quantile time window
calibration.

After this patch, statistics summary quantile aging params
`age_bucket_count` and `max_age_time` [1] could be configured:

  crud.cfg{
      stats_quantile_age_bucket_count = 3,
      stats_quantile_max_age_time = 30,
  }

Only type validation is conducted in crud.cfg, every other validation is
performed by metrics itself.

1. https://www.tarantool.io/ru/doc/latest/book/monitoring/api_reference/#summary

Part of #286

Author: DifferentialOrange

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ## [Unreleased]
 
 ### Added
+* Make metrics quantile collector age params configurable (#286).
 
 ### Changed
 

README.md

@@ -797,7 +797,17 @@ crud.cfg{stats_quantile_tolerated_error = 1e-4}
 ```
 See [tarantool/metrics#189](https://github.com/tarantool/metrics/issues/189) for
 details about the issue.
-
+You can also configure quantile `age_bucket_count` (default: 2) and
+`max_age_time` (in seconds, default: 60):
+```lua
+crud.cfg{
+    stats_quantile_age_bucket_count = 3,
+    stats_quantile_max_age_time = 30,
+}
+```
+See [`metrics` summary API](https://www.tarantool.io/ru/doc/latest/book/monitoring/api_reference/#summary)
+for details. These parameters can be used to smooth time window move
+or reduce the amount on `-nan` gaps for low request frequency applications.
 
 `select` section additionally contains `details` collectors.
 ```lua

crud/cfg.lua

@@ -29,6 +29,14 @@ local function set_defaults_if_empty(cfg)
         cfg.stats_quantile_tolerated_error = stats.DEFAULT_QUANTILE_TOLERATED_ERROR
     end
 
+    if cfg.stats_quantile_age_buckets_count == nil then
+        cfg.stats_quantile_age_buckets_count = stats.DEFAULT_QUANTILE_AGE_BUCKET_COUNT
+    end
+
+    if cfg.stats_quantile_max_age_time == nil then
+        cfg.stats_quantile_max_age_time = stats.DEFAULT_QUANTILE_MAX_AGE_TIME
+    end
+
     return cfg
 end
 
@@ -38,7 +46,9 @@ local function configure_stats(cfg, opts)
     if  (opts.stats == nil)
     and (opts.stats_driver == nil)
     and (opts.stats_quantiles == nil)
-    and (opts.stats_quantile_tolerated_error == nil) then
+    and (opts.stats_quantile_tolerated_error == nil)
+    and (opts.stats_quantile_age_buckets_count == nil)
+    and (opts.stats_quantile_max_age_time == nil) then
         return
     end
 
@@ -58,11 +68,21 @@ local function configure_stats(cfg, opts)
         opts.stats_quantile_tolerated_error = cfg.stats_quantile_tolerated_error
     end
 
+    if opts.stats_quantile_age_buckets_count == nil then
+        opts.stats_quantile_age_buckets_count = cfg.stats_quantile_age_buckets_count
+    end
+
+    if opts.stats_quantile_max_age_time == nil then
+        opts.stats_quantile_max_age_time = cfg.stats_quantile_max_age_time
+    end
+
     if opts.stats == true then
         stats.enable{
             driver = opts.stats_driver,
             quantiles = opts.stats_quantiles,
             quantile_tolerated_error = opts.stats_quantile_tolerated_error,
+            quantile_age_buckets_count = opts.stats_quantile_age_buckets_count,
+            quantile_max_age_time = opts.stats_quantile_max_age_time,
         }
     else
         stats.disable()
@@ -72,6 +92,8 @@ local function configure_stats(cfg, opts)
     rawset(cfg, 'stats_driver', opts.stats_driver)
     rawset(cfg, 'stats_quantiles', opts.stats_quantiles)
     rawset(cfg, 'stats_quantile_tolerated_error', opts.stats_quantile_tolerated_error)
+    rawset(cfg, 'stats_quantile_age_buckets_count', opts.stats_quantile_age_buckets_count)
+    rawset(cfg, 'stats_quantile_max_age_time', opts.stats_quantile_max_age_time)
 end
 
 --- Configure CRUD module.
@@ -107,6 +129,21 @@ end
 --  See https://github.com/tarantool/metrics/issues/189 for issue details.
 --  Decreasing the value increases computational load.
 --
+-- @number[opt=2] opts.stats_quantile_age_buckets_count
+--  Count of summary quantile buckets.
+--  See tarantool/metrics summary API for details:
+--  https://www.tarantool.io/ru/doc/latest/book/monitoring/api_reference/#summary
+--  Increasing the value smoothes time window move,
+--  but consumes additional memory and CPU.
+--
+-- @number[opt=60] opts.stats_quantile_max_age_time
+--  Duration of each bucket’s lifetime in seconds.
+--  See tarantool/metrics summary API for details:
+--  https://www.tarantool.io/ru/doc/latest/book/monitoring/api_reference/#summary
+--  Smaller bucket lifetime results in smaller time window for quantiles,
+--  but more CPU is spent on bucket rotation. If your application has low request
+--  frequency, increase the value to reduce the amount of `-nan` gaps in quantile values.
+--
 -- @return Configuration table.
 --
 local function __call(self, opts)
@@ -115,6 +152,8 @@ local function __call(self, opts)
         stats_driver = '?string',
         stats_quantiles = '?boolean',
         stats_quantile_tolerated_error = '?number',
+        stats_quantile_age_buckets_count = '?number',
+        stats_quantile_max_age_time = '?number',
     })
 
     opts = table.deepcopy(opts) or {}

crud/stats/init.lua

@@ -90,13 +90,30 @@ end
 --  If quantile value is -Inf, try to decrease quantile tolerated error.
 --  See https://github.com/tarantool/metrics/issues/189 for issue details.
 --
+-- @number[opt=2] opts.quantile_age_buckets_count
+--  Count of summary quantile buckets.
+--  See tarantool/metrics summary API for details:
+--  https://www.tarantool.io/ru/doc/latest/book/monitoring/api_reference/#summary
+--  Increasing the value smoothes time window move,
+--  but consumes additional memory and CPU.
+--
+-- @number[opt=60] opts.quantile_max_age_time
+--  Duration of each bucket’s lifetime in seconds.
+--  See tarantool/metrics summary API for details:
+--  https://www.tarantool.io/ru/doc/latest/book/monitoring/api_reference/#summary
+--  Smaller bucket lifetime results in smaller time window for quantiles,
+--  but more CPU is spent on bucket rotation. If your application has low request
+--  frequency, increase the value to reduce the amount of `-nan` gaps in quantile values.
+--
 -- @treturn boolean Returns `true`.
 --
 function stats.enable(opts)
     checks({
         driver = '?string',
         quantiles = '?boolean',
         quantile_tolerated_error = '?number',
+        quantile_age_buckets_count = '?number',
+        quantile_max_age_time = '?number',
     })
 
     StatsError:assert(
@@ -122,10 +139,20 @@ function stats.enable(opts)
         opts.quantile_tolerated_error = stats.DEFAULT_QUANTILE_TOLERATED_ERROR
     end
 
+    if opts.quantile_age_buckets_count == nil then
+        opts.quantile_age_buckets_count = stats.DEFAULT_QUANTILE_AGE_BUCKET_COUNT
+    end
+
+    if opts.quantile_max_age_time == nil then
+        opts.quantile_max_age_time = stats.DEFAULT_QUANTILE_MAX_AGE_TIME
+    end
+
     -- Do not reinit if called with same options.
     if internal.driver == opts.driver
     and internal.quantiles == opts.quantiles
-    and internal.quantile_tolerated_error == opts.quantile_tolerated_error then
+    and internal.quantile_tolerated_error == opts.quantile_tolerated_error
+    and internal.quantile_age_buckets_count == opts.quantile_age_buckets_count
+    and internal.quantile_max_age_time == opts.quantile_max_age_time then
         return true
     end
 
@@ -136,11 +163,15 @@ function stats.enable(opts)
 
     internal:get_registry().init{
         quantiles = opts.quantiles,
-        quantile_tolerated_error = opts.quantile_tolerated_error
+        quantile_tolerated_error = opts.quantile_tolerated_error,
+        quantile_age_buckets_count = opts.quantile_age_buckets_count,
+        quantile_max_age_time = opts.quantile_max_age_time,
     }
 
     internal.quantiles = opts.quantiles
     internal.quantile_tolerated_error = opts.quantile_tolerated_error
+    internal.quantile_age_buckets_count = opts.quantile_age_buckets_count
+    internal.quantile_max_age_time = opts.quantile_max_age_time
 
     return true
 end
@@ -162,7 +193,9 @@ function stats.reset()
     internal:get_registry().destroy()
     internal:get_registry().init{
         quantiles = internal.quantiles,
-        quantile_tolerated_error = internal.quantile_tolerated_error
+        quantile_tolerated_error = internal.quantile_tolerated_error,
+        quantile_age_buckets_count = internal.quantile_age_buckets_count,
+        quantile_max_age_time = internal.quantile_max_age_time,
     }
 
     return true
@@ -184,6 +217,9 @@ function stats.disable()
     internal:get_registry().destroy()
     internal.driver = nil
     internal.quantiles = nil
+    internal.quantile_tolerated_error = nil
+    internal.quantile_age_buckets_count = nil
+    internal.quantile_max_age_time = nil
 
     return true
 end
@@ -495,4 +531,10 @@ stats.internal = internal
 --- Default metrics quantile precision.
 stats.DEFAULT_QUANTILE_TOLERATED_ERROR = 1e-3
 
+--- Default metrics quantile bucket count.
+stats.DEFAULT_QUANTILE_AGE_BUCKET_COUNT = 2
+
+--- Default metrics quantile bucket lifetime.
+stats.DEFAULT_QUANTILE_MAX_AGE_TIME = 60
+
 return stats

crud/stats/local_registry.lua

@@ -28,12 +28,20 @@ local StatsLocalError = errors.new_class('StatsLocalError', {capture_stack = fal
 -- @number opts.quantile_tolerated_error
 --  Quantiles is not supported for local, so the value is ignored.
 --
+-- @number opts.quantile_age_buckets_count
+--  Quantiles is not supported for local, so the value is ignored.
+--
+-- @number opts.quantile_max_age_time
+--  Quantiles is not supported for local, so the value is ignored.
+--
 -- @treturn boolean Returns `true`.
 --
 function registry.init(opts)
     dev_checks({
         quantiles = 'boolean',
         quantile_tolerated_error = 'number',
+        quantile_age_buckets_count = 'number',
+        quantile_max_age_time = 'number',
     })
 
     StatsLocalError:assert(opts.quantiles == false,

crud/stats/metrics_registry.lua

@@ -31,11 +31,6 @@ local metric_name = {
 
 local LATENCY_QUANTILE = 0.99
 
-local DEFAULT_AGE_PARAMS = {
-    age_buckets_count = 2,
-    max_age_time = 60,
-}
-
 --- Check if application supports metrics rock for registry
 --
 --  `metrics >= 0.10.0` is required.
@@ -87,19 +82,39 @@ end
 --  If quantile value is -Inf, try to decrease quantile tolerated error.
 --  See https://github.com/tarantool/metrics/issues/189 for issue details.
 --
+-- @number[opt=2] opts.quantile_age_buckets_count
+--  Count of summary quantile buckets.
+--  See tarantool/metrics summary API for details:
+--  https://www.tarantool.io/ru/doc/latest/book/monitoring/api_reference/#summary
+--  Increasing the value smoothes time window move,
+--  but consumes additional memory and CPU.
+--
+-- @number[opt=60] opts.quantile_max_age_time
+--  Duration of each bucket’s lifetime in seconds.
+--  See tarantool/metrics summary API for details:
+--  https://www.tarantool.io/ru/doc/latest/book/monitoring/api_reference/#summary
+--  Smaller bucket lifetime results in smaller time window for quantiles,
+--  but more CPU is spent on bucket rotation. If your application has low request
+--  frequency, increase the value to reduce the amount of `-nan` gaps in quantile values.
+--
 -- @treturn boolean Returns `true`.
 --
 function registry.init(opts)
     dev_checks({
         quantiles = 'boolean',
         quantile_tolerated_error = 'number',
+        quantile_age_buckets_count = 'number',
+        quantile_max_age_time = 'number',
     })
 
     local quantile_params = nil
     local age_params = nil
     if opts.quantiles == true then
         quantile_params = {[LATENCY_QUANTILE] = opts.quantile_tolerated_error}
-        age_params = DEFAULT_AGE_PARAMS
+        age_params = {
+            age_buckets_count = opts.quantile_age_buckets_count,
+            max_age_time = opts.quantile_max_age_time,
+        }
     end
 
     internal.registry = {}

test/integration/cfg_test.lua

@@ -27,6 +27,8 @@ group.test_defaults = function(g)
         stats_driver = stats.get_default_driver(),
         stats_quantiles = false,
         stats_quantile_tolerated_error = 1e-3,
+        stats_quantile_age_buckets_count = 2,
+        stats_quantile_max_age_time = 60,
     })
 end
 
@@ -100,3 +102,47 @@ group.test_gh_284_preset_stats_quantile_tolerated_error_is_preserved = function(
     t.assert_equals(cfg.stats_quantile_tolerated_error, 1e-4,
         'Preset stats_quantile_tolerated_error presents')
 end
+
+group.test_gh_284_preset_stats_quantile_age_buckets_count_is_preserved = function(g)
+    -- Arrange some cfg values so test case will not depend on defaults.
+    local cfg = g.cluster:server('router'):eval(
+        "return require('crud').cfg(...)",
+        {{ stats = false }})
+    t.assert_equals(cfg.stats, false)
+
+    -- Set stats_age_buckets_count.
+    local cfg = g.cluster:server('router'):eval(
+        "return require('crud').cfg(...)",
+        {{ stats_quantile_age_buckets_count = 3 }})
+    t.assert_equals(cfg.stats_quantile_age_buckets_count, 3)
+
+    -- Set another cfg parameter, assert preset stats_quantile_age_buckets_count presents.
+    local cfg = g.cluster:server('router'):eval(
+        "return require('crud').cfg(...)",
+        {{ stats = true }})
+    t.assert_equals(cfg.stats, true)
+    t.assert_equals(cfg.stats_quantile_age_buckets_count, 3,
+        'Preset stats_quantile_age_buckets_count presents')
+end
+
+group.test_gh_284_preset_stats_quantile_max_age_time_is_preserved = function(g)
+    -- Arrange some cfg values so test case will not depend on defaults.
+    local cfg = g.cluster:server('router'):eval(
+        "return require('crud').cfg(...)",
+        {{ stats = false }})
+    t.assert_equals(cfg.stats, false)
+
+    -- Set stats_age_buckets_count.
+    local cfg = g.cluster:server('router'):eval(
+        "return require('crud').cfg(...)",
+        {{ stats_quantile_max_age_time = 30 }})
+    t.assert_equals(cfg.stats_quantile_max_age_time, 30)
+
+    -- Set another cfg parameter, assert preset stats_quantile_max_age_time presents.
+    local cfg = g.cluster:server('router'):eval(
+        "return require('crud').cfg(...)",
+        {{ stats = true }})
+    t.assert_equals(cfg.stats, true)
+    t.assert_equals(cfg.stats_quantile_max_age_time, 30,
+        'Preset stats_quantile_max_age_time presents')
+end

test/integration/stats_test.lua

@@ -55,7 +55,10 @@ local function enable_stats(g, params)
         require('crud').cfg{
             stats = true,
             stats_driver = params.driver,
-            stats_quantiles = params.quantiles
+            stats_quantiles = params.quantiles,
+            stats_quantile_tolerated_error = 1e-3,
+            stats_quantile_age_buckets_count = 3,
+            stats_quantile_max_age_time = 60,
         }
     ]], { params })
 end