summary: age buckets added (#193)

Co-authored-by: Roman Proskin <[email protected]>
Co-authored-by: Georgy Moiseev <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -13,6 +13,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - `tnt_cartridge_issues` gathers only local issues [#211](https://github.com/tarantool/metrics/issues/211)
 
+### Added
+- Age buckets in `summary`
+
 ## [0.8.0] - 2021-04-13
 ### Added
 - New default metrics: cpu_user_time, cpu_system_time

README.md

@@ -118,10 +118,11 @@ Summary is exposed as multiple numerical values:
 ```lua
 local metrics = require('metrics')
 
--- create a summary
+-- create a summary with a sliding window of 5 age buckets and 60s bucket lifetime
 local http_requests_latency = metrics.summary(
     'http_requests_latency', 'HTTP requests total',
-    {[0.5]=0.01, [0.9]=0.01, [0.99]=0.01}
+    {[0.5]=0.01, [0.9]=0.01, [0.99]=0.01},
+    {max_age_time = 60, age_buckets_count = 5}
 )
 
 -- somewhere in the HTTP requests middleware:
@@ -212,10 +213,10 @@ via configuration.
    local metrics = cartridge.service_get('metrics')
    ```
 
-5. There is an ability in Tarantool Cartridge >= '2.4.0' to set a zone for each 
-   server in cluster. If zone was set for the server 'zone' label for all metrics 
-   of this server will be added.
-   
+5. There is an ability in Tarantool Cartridge >= '2.4.0' to set a zone for each
+   server in a cluster. If a zone was set for the server 'zone' label will be added
+   for all metrics on this server.
+
 ## Next steps
 
 See:

doc/locale/en/api_reference.pot

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Monitoring \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2021-04-02 01:27+0300\n"
+"POT-Creation-Date: 2021-05-26 12:00+0000\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <[email protected]>\n"
@@ -139,7 +139,10 @@ msgstr ""
 msgid "Registers a new summary. Quantile computation is based on the algorithm `\"Effective computation of biased quantiles over data streams\" <https://ieeexplore.ieee.org/document/1410103>`_"
 msgstr ""
 
-msgid "Quantiles to observe in the form ``{quantile = error, ... }``. For example: ``{[0.5]=0.01, [0.9]=0.01, [0.99]=0.01}``"
+msgid "A list of 'targeted' φ-quantiles in the form ``{quantile = error, ... }``. For example: ``{[0.5]=0.01, [0.9]=0.01, [0.99]=0.01}``. A targeted φ-quantile is specified in the form of a φ-quantile and tolerated error. For example a ``{[0.5] = 0.1}`` means that the median (= 50th percentile) should be returned with 10 percent error. Note that percentiles and quantiles are the same concept, except percentiles are expressed as percentages. The φ-quantile must be in the interval [0, 1]. Note that a lower tolerated error for a φ-quantile results in higher usage of resources (memory and CPU) to calculate the summary."
+msgstr ""
+
+msgid "Table of summary parameters, used for configuring sliding window of time. 'Sliding window' consists of several buckets to store observations. New observations are added to each bucket. After a time period, the 'head' bucket (bucket from which observations are collected) is reset and the next bucket becomes a new 'head'. I.e. each bucket will store observations for ``max_age_time * age_buckets_count`` seconds before it will be reset. ``max_age_time`` sets the duration of each bucket lifetime, i.e., how long observations are kept before they are discarded, in seconds ``age_buckets_count`` sets the number of buckets of the time window. It determines the number of buckets used to exclude observations that are older than ``max_age_time`` from the Summary. The value is a trade-off between resources (memory and CPU for maintaining the bucket) and how smooth the time window is moved. Default value is `{max_age_time = math.huge, age_buckets_count = 1}`"
 msgstr ""
 
 msgid "Summary object"
@@ -163,7 +166,10 @@ msgstr ""
 msgid "Value to put in the data stream."
 msgstr ""
 
-msgid "Returns a concatenation of ``counter_obj:collect()`` across all internal counters of ``summary_obj``. For ``observation`` description, see :ref:`counter_obj:collect() <counter-collect>`."
+msgid "A table containing label names as keys, label values as values (table). A new value is observed by all internal counters with these labels specified. Label ``\"quantile\"`` are not allowed in ``summary``. It will be added automatically. If ``max_age_time`` and ``age_buckets_count`` are set, the observed value will be added to each bucket."
+msgstr ""
+
+msgid "Returns a concatenation of ``counter_obj:collect()`` across all internal counters of ``summary_obj``. For ``observation`` description, see :ref:`counter_obj:collect() <counter-collect>`. If ``max_age_time`` and ``age_buckets_count`` are set, quantile observations will be collect only from the head bucket in sliding window and not from every bucket."
 msgstr ""
 
 msgid "Labels"

doc/locale/en/metrics_reference.pot

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Monitoring \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2021-05-27 09:04+0000\n"
+"POT-Creation-Date: 2021-05-28 12:41+0000\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <[email protected]>\n"

doc/monitoring/api_reference.rst

@@ -162,12 +162,35 @@ Summary
 
 ..  function:: summary(name [, help, objectives])
 
-    Registers a new summary. Quantile computation is based on the algorithm `"Effective computation of biased quantiles over data streams" <https://ieeexplore.ieee.org/document/1410103>`_
+    Registers a new summary. Quantile computation is based on the algorithm
+    `"Effective computation of biased quantiles over data streams" <https://ieeexplore.ieee.org/document/1410103>`_
 
     :param string   name: Collector name. Must be unique.
     :param string   help: Help description.
-    :param table objectives: Quantiles to observe in the form ``{quantile = error, ... }``.
-                          For example: ``{[0.5]=0.01, [0.9]=0.01, [0.99]=0.01}``
+    :param table objectives: A list of 'targeted' φ-quantiles in the form ``{quantile = error, ... }``.
+        For example: ``{[0.5]=0.01, [0.9]=0.01, [0.99]=0.01}``.
+        A targeted φ-quantile is specified in the form of a φ-quantile and tolerated
+        error. For example a ``{[0.5] = 0.1}`` means that the median (= 50th
+        percentile) should be returned with 10 percent error. Note that
+        percentiles and quantiles are the same concept, except percentiles are
+        expressed as percentages. The φ-quantile must be in the interval [0, 1].
+        Note that a lower tolerated error for a φ-quantile results in higher
+        usage of resources (memory and CPU) to calculate the summary.
+
+    :param table params: Table of summary parameters, used for configuring sliding
+        window of time. 'Sliding window' consists of several buckets to store observations.
+        New observations are added to each bucket. After a time period, the 'head' bucket
+        (bucket from which observations are collected) is reset and the next bucket becomes a
+        new 'head'. I.e. each bucket will store observations for
+        ``max_age_time * age_buckets_count`` seconds before it will be reset.
+        ``max_age_time`` sets the duration of each bucket lifetime, i.e., how long
+        observations are kept before they are discarded, in seconds
+        ``age_buckets_count`` sets the number of buckets of the time window. It
+        determines the number of buckets used to exclude observations that are
+        older than ``max_age_time`` from the Summary. The value is
+        a trade-off between resources (memory and CPU for maintaining the bucket)
+        and how smooth the time window is moved.
+        Default value is `{max_age_time = math.huge, age_buckets_count = 1}`
 
     :return: Summary object
 
@@ -190,16 +213,23 @@ Summary
         Records a new value in a summary.
 
         :param number        num: Value to put in the data stream.
-        :param table label_pairs: Table containing label names as keys,
+        :param table label_pairs: A table containing label names as keys,
                                   label values as values (table).
                                   A new value is observed by all internal counters
                                   with these labels specified.
+                                  Label ``"quantile"`` are not allowed in ``summary``.
+                                  It will be added automatically.
+                                  If ``max_age_time`` and ``age_buckets_count`` are set,
+                                  the observed value will be added to each bucket.
 
     ..  method:: collect()
 
         Returns a concatenation of ``counter_obj:collect()`` across all internal
         counters of ``summary_obj``. For ``observation`` description,
         see :ref:`counter_obj:collect() <counter-collect>`.
+        If ``max_age_time`` and ``age_buckets_count`` are set, quantile observations
+        will be collect only from the head bucket in sliding window and not from every
+        bucket.
 
 .. _labels:
 
@@ -452,10 +482,11 @@ Using summaries:
 
     local metrics = require('metrics')
 
-    -- create a summary
+    -- create a summary with a window of 5 age buckets and 60s bucket lifetime
     local http_requests_latency = metrics.summary(
         'http_requests_latency', 'HTTP requests total',
-        {[0.5]=0.01, [0.9]=0.01, [0.99]=0.01}
+        {[0.5]=0.01, [0.9]=0.01, [0.99]=0.01},
+        {max_age_time = 60, age_buckets_count = 5}
     )
 
     -- somewhere in the HTTP requests middleware:

metrics/collectors/summary.lua

@@ -6,20 +6,28 @@ local fiber = require('fiber')
 
 local Summary = Shared:new_class('summary', {'observe_latency'})
 
-function Summary:new(name, help, objectives)
+function Summary:new(name, help, objectives, params)
+    params = params or {}
     local obj = Shared.new(self, name, help)
 
     obj.count_collector = Counter:new(name .. '_count', help)
     obj.sum_collector = Counter:new(name .. '_sum', help)
     obj.objectives = objectives
+    obj.max_age_time = params.max_age_time
+    obj.age_buckets_count = params.age_buckets_count or 1
+    obj.observations = {}
 
+    obj.quantiles = {}
+    for q, _ in pairs(objectives) do
+        table.insert(obj.quantiles, q)
+    end
     return obj
 end
 
 function Summary.check_quantiles(objectives)
     for k, v in pairs(objectives) do
         if type(k) ~= 'number' then return false end
-        if k >= 1 or k < 0 then return false end
+        if k > 1 or k < 0 then return false end
         if type(v) ~= 'number' then return false end
     end
     return true
@@ -31,35 +39,69 @@ function Summary:set_registry(registry)
     self.sum_collector:set_registry(registry)
 end
 
+function Summary:rotate_age_buckets(key)
+    local obs_object = self.observations[key]
+    local old_index = obs_object.head_bucket_index
+    obs_object.head_bucket_index = ((obs_object.head_bucket_index + 1) % self.age_buckets_count) + 1
+    Quantile.Reset(obs_object.buckets[old_index])
+    obs_object.last_rotate = os.time()
+end
+
 function Summary:observe(num, label_pairs)
     label_pairs = label_pairs or {}
-
+    if label_pairs.quantile then
+        error('Label "quantile" are not allowed in summary')
+    end
     self.count_collector:inc(1, label_pairs)
     self.sum_collector:inc(num, label_pairs)
     if self.objectives then
+        local now = os.time()
         local key = self.make_key(label_pairs)
+
         if not self.observations[key] then
-            self.observations[key] = Quantile.NewTargeted(self.objectives)
+            local obs_object = {
+                buckets = {},
+                head_bucket_index = 1,
+                last_rotate = now,
+                label_pairs = label_pairs,
+            }
             self.label_pairs[key] = label_pairs
+            for i = 1, self.age_buckets_count do
+                local quantile_obj = Quantile.NewTargeted(self.objectives)
+                Quantile.Insert(quantile_obj, num)
+                obs_object.buckets[i] = quantile_obj
+            end
+            self.observations[key] = obs_object
+        else
+            local obs_object = self.observations[key]
+            if self.age_buckets_count > 1 and now - obs_object.last_rotate >= self.max_age_time then
+                self:rotate_age_buckets(key)
+            end
+            for _, bucket in ipairs(obs_object.buckets) do
+                Quantile.Insert(bucket, num)
+            end
         end
-        Quantile.Insert(self.observations[key], num)
     end
 end
 
-
 function Summary:collect_quantiles()
-    if next(self.observations) == nil then
+    if not self.objectives or next(self.observations) == nil then
         return {}
     end
+
     local result = {}
+    local now = os.time()
     for key, observation in pairs(self.observations) do
-        for objective, _ in pairs(self.objectives) do
-            local label_pairs = table.deepcopy(self:append_global_labels(self.label_pairs[key]))
+        if self.age_buckets_count > 1 and now - observation.last_rotate >= self.max_age_time then
+            self:rotate_age_buckets(key)
+        end
+        for _, objective in ipairs(self.quantiles) do
+            local label_pairs = table.deepcopy(self:append_global_labels(observation.label_pairs))
             label_pairs.quantile = objective
             local obs = {
                 metric_name = self.name,
                 label_pairs = label_pairs,
-                value = Quantile.Query(observation, objective),
+                value = Quantile.Query(observation.buckets[observation.head_bucket_index], objective),
                 timestamp = fiber.time64(),
             }
             table.insert(result, obs)
@@ -70,16 +112,29 @@ end
 
 function Summary:collect()
     local result = {}
-    for _, obs in pairs(self.count_collector:collect()) do
+    for _, obs in ipairs(self.count_collector:collect()) do
         table.insert(result, obs)
     end
-    for _, obs in pairs(self.sum_collector:collect()) do
+    for _, obs in ipairs(self.sum_collector:collect()) do
         table.insert(result, obs)
     end
-    for _, obs in pairs(self:collect_quantiles()) do
+    for _, obs in ipairs(self:collect_quantiles()) do
         table.insert(result, obs)
     end
     return result
 end
 
+-- debug function to get observation quantiles from summary
+-- returns array of quantile objects or
+-- single quantile object if summary has only one bucket
+function Summary:get_observations(label_pairs)
+    local key = self.make_key(label_pairs or {})
+    local obs = self.observations[key]
+    if self.age_buckets_count > 1 then
+        return obs
+    else
+        return obs.buckets[1]
+    end
+end
+
 return Summary

metrics/http_middleware.lua

@@ -15,6 +15,11 @@ export.DEFAULT_QUANTILES = {
     [0.99] = 0.01,
 }
 
+export.DEFAULT_SUMMARY_PARAMS = {
+    max_age_time = 60,
+    age_buckets_count = 5,
+}
+
 --- Build default histogram collector
 --
 -- @string[opt='histogram'] type_name `histogram` or `average` or `summary`
@@ -29,7 +34,7 @@ function export.build_default_collector(type_name, name, help)
     if type_name == 'histogram' then
         extra = {export.DEFAULT_HISTOGRAM_BUCKETS}
     elseif type_name == 'summary' then
-        extra = {export.DEFAULT_QUANTILES}
+        extra = {export.DEFAULT_QUANTILES, export.DEFAULT_SUMMARY_PARAMS}
     elseif type_name == 'average' then
         log.warn('Average collector is deprecated. Use summary collector instead.')
     else

metrics/init.lua

@@ -56,13 +56,28 @@ local function histogram(name, help, buckets)
     return registry:find_or_create(Histogram, name, help, buckets)
 end
 
-local function summary(name, help, objectives)
-    checks('string', '?string', '?table')
+local function summary(name, help, objectives, params)
+    checks('string', '?string', '?table', {
+        age_buckets_count = '?number',
+        max_age_time = '?number',
+    })
     if objectives ~= nil and not Summary.check_quantiles(objectives) then
         error('Invalid value for objectives')
     end
+    params = params or {}
+    local age_buckets_count = params.age_buckets_count
+    local max_age_time = params.max_age_time
+    if max_age_time and max_age_time <= 0 then
+        error('Max age must be positive')
+    end
+    if age_buckets_count and age_buckets_count < 1 then
+        error('Age buckets count must be greater or equal than one')
+    end
+    if (max_age_time and not age_buckets_count) or (not max_age_time and age_buckets_count) then
+        error('Age buckets count and max age must be present only together')
+    end
 
-    return registry:find_or_create(Summary, name, help, objectives)
+    return registry:find_or_create(Summary, name, help, objectives, params)
 end
 
 local function set_global_labels(label_pairs)

metrics/quantile.lua

@@ -284,6 +284,12 @@ function quantile.Reset(stream_obj)
     stream_obj.stream.n = 0
 	stream_obj.b_len = 0
 	stream_obj.stream.l_len = 0
+	for i = 1, stream_obj.__max_samples * 2 + 1 do
+        stream_obj.stream.l[i] = inf_obj
+	end
+	for i = 0, stream_obj.__max_samples - 1 do
+        stream_obj.b[i] = math.huge
+	end
 end
 
 return quantile