Expand documentation

[yngvar-antonsson]

• Documentation (README and rst)

Close #111
Close #264
Close #311

[patiencedaur]

Though implemented differently, collectors in Tarantool metrics are very similar to the ones used in Prometheus. So you can check the corresponding pages of the Prometheus doc to get some insight into them.

Also, here are some comments from @ yngvar-antonsson that may be useful to the translator:

1. Regarding counter.obj:functions
   Все коллекторы в себе хранят один или несколько списков с лейблами, у каждого такого списка будет свое значение метрики. Грубо говоря, это такая табличка {"{label1 = label_value1, label2 = label_value2}" = counter_value} и мы можем инкрементировать/удалить значения для какого-то набора лейблов

2. В примере counter_obj:collect() - это один объект «observation». Каждый коллект возвращает несколько таких объектов. Поля у каждого из них зарезервирвоаны и всегда будет примерно такой формат. В разделе labels описаны label_pairs, это один из элементов объекта observation

3. Gauge --- это такой коллектор, которому можно выставить любое значение (set), увеличить или уменьшить его на любое число (inc/dec). Может принимать любое число, в отличие от каунтера, который всегда либо увеличивается, либо сбрасывается (reset)

4. Внутри у гистограммы и саммари действительно несколько коллекторов, но вообще и гистограмма, и саммари - это тоже коллектор (просто составлен из нескольких других коллекторов)

5. metrics.enable_default_metrics(include, exclude): {‘vinyl’, ’luajit’, ‘memory’} - вот так выглядит и exclude и include. Со списками действительно путаница получилась: You can see the full list of default metrics in the API reference - тут имелось в виду, что все возможные значения для таблиц include и exclude можно посмотреть в описании функции metrics.enable_default_metrics(include, exclude) (API ref) , а в ее описании должно быть написано, что если хотите посмотреть, а какие конкретно метрики подразумеваются в каждом топике - сходите в metrics ref и посмотрите. К сожалению, тут уже начинаются сложности, потому что в metrics reference другая группировка этих метрик

6. Registry - это такое внутреннее хранилище для всех созданных коллекторов, лейблов и колбеков

7. exporter - это json/prometheus/graphite exporter (либо некоторый кастомный экспортер, который пользователь ручками напишет) - просто обобщение на все экспортеры

8. Как работает le (less than equal) в Гистограмме.
   Допустим, у нас есть некоторый набор значений
   Например, [1, 1, 2, 2, 2, 2, 5, 10 ]
   У Гистограммы есть бакеты, например [1, 5, 10] - эти числа попадают в le, бакеты задаются при создании объекта гистограммы
   Гистограмма обрабатывает эти чиселки и считает, какое количество значений <= каждому бакету
   То есть для бакета le = 1 будет значение 2 (т.к в наборе значений две единички)
   для бакета le = 1 будет значение 7 (т.к. в наборе значений две единицы, четыре двойки и одна пятерка)
   И так далее
   Когда вызывается метод Histogram:observe(num, label_pairs), число num увеличивает значения для каждого бакета, для которого выполняется num <= le

9. Про summary и квантили.
   Когда создаешь объект саммари, нужно указать список квантилей, за которыми хотим наблюдать, например {[0.5] = 0.1, [0.9] = 0.1} (аналогично в гистограмме нужно указать список бакетов {1,2,3,100})
   Лейблы le и quantile добавляются автоматически, если кто-то попытается добавить их например так: observe(10, {quantile = "0.5"}) - это запрещено. А вообще лейблы при создании коллектора не указываются никогда. Их нужно передавать в функции inc/set/dec/observe вторым аргументом

10. All collectors support providing label_pairs on data modification.
    вот это именно про передачу лейблов при наблюдении значений. providing делает разработчик, когда вызывает методы inc/dec/set/observe для кастомных метрик или сам модуль метрикс для дефолтных метрик

11. Как выглядит label_pairs.
    label_pairs - это табличка, в которой ключами будут названия лейблов, а значениями - некоторая информация, которая друг от друга отличает наблюдение
    Вот например:
    Есть некоторый gauge, который представляет собой количество людей в разных классах школы
    Этот объект используется для хранения информации о количестве учеников по каждому классу, а отличает их по значению label_pairs
gauge:set(10, {class = ’11B’})

gauge:set(15, {class = ’10A’})

если потом мы вызовем метод gauge:collect(),
он вернет следующее:

{            
            {
                label_pairs: {class = ’11B’},   
                timestamp: 10000000,
                value: 10,
                metric_name: ‘students’,
            },
            {
                label_pairs: {class = ’10A’}, 
                timestamp: 10000001,
                value: 15,
                metric_name: ‘students’,
            },
}