Revision as of 17:06, 17 May 2023

На данной странице приводится описание REST API загрузки статистики и доступные типы статистики.

Описание элементов REST API для загрузки статистики

Система поддерживает загрузку статистики для проектов и отдельных веток проектов:

Для проекта: GET /api/projects/{project_id}/statistics/{название типа статистики}

Для ветки: GET /api/projects/{project_id}/branch/{branch_id}/statistics/{название типа статистики}

Внимание! Как и для других типов запросов публичного REST API, в хедере запросов статистики необходимо передавать токен авторизации — Authorization: Bearer <token> — полученный с помощью запроса к /api/public/login (см. Публичные REST запросы).

Параметры запросов статистики

Запросы статистики поддерживают следующие необязательные параметры:

Параметр	Формат	Значение по умолчанию	Описание
from	время в одном из форматов поддерживаемых go	—	начало интересующего отрезка времени
to	время в одном из форматов поддерживаемых go	—	конец интересующего отрезка времени
bin-base	время в одном из форматов поддерживаемых go	`1970-01-01T00:00:00Z`	базовый момент времени, от которого отсчитываются временные группы
bin-stride	интервал времени, заданный с помощью строки вида `1y2M3w4d5h6m7s`	`1s`	размер временной группы (bin)

Форматы времени поддерживаемые go

https://pkg.go.dev/time#pkg-constants

Наиболее предпочтительным является формат RFC 3339 — 2006-01-02T15:04:05Z07:00

Формат строки интервала времени

Строка должна состоять из подстрок, соответствующих регулярному выражению (?P<val>[0-9]+)(?P<unit>[smhdwMy]), где:

группа val — положительное целое число — количество временных единиц;
группа unit — одна из букв 's'(секунды), 'm'(минуты), 'h'(часы), 'd'(дни), 'w'(недели), 'M'(месяцы), 'y'(годы) — тип временной единицы.

Примеры временных интервалов:

24h — 24 часа
1m1m1m1m1m — 5 минут
5d12h30m30s — 5 дней + 12 часов + 30 минут + 30 секунд

Форматы ответов

Форматы ответов запросов статистики для проектов (projects/{}/statistics/...) и веток (projects/{}/branch/{}/statistics/...) различаются тем, что для проекта возвращается список статистик веток, входящих в проект.

Ответ для запроса статистики проекта

{
    "status": "OK",
    "result": {
        "Branches": [{объект статистики ветки}, ...]
    }
}

Ответ для запроса статистики ветки

{
    "status": "OK",
    "result": {объект статистики ветки}
}

Для каждого типа статистики, {объект статистики ветки} состоит из полей:

ContainerInfo — информация о ветке;
- ID — uuid-идентификатор ветки
- Name — название ветки
- Type — int-идентификатор типа контейнера: для ветки всегда равен двум (2)
TimeSerie — временной ряд, содержащий список временных групп, для которых были найдены события
- Items — список элементов временного ряда
  - Time — время начала временной группы (bin) в формате ISO 8601
  - Value — объект-значение с данными соответствующими типу статистики
  - Description (может отсутствовать) — дополнительные данные, относящиеся к переданному объекту-значению

{
    "ContainerInfo": {
        "ID": "uuid-идентификатор ветки",
        "Name": "название ветки",
        "Type": 2
    },
    "TimeSerie": {
        "Items": [
            {
                "Time": "2023-04-03T00:00:00Z",
                "Value": {объект-значение с данными статистики},
                "Description": {дополнительные данные}
            }, ...
        ]
    }
}

Логика формирования временных групп (bin)

События, появляющиеся в системе в течение времени, могут быть сгруппированы во временные группы (bin).

Временные группы задаются путём установки базового времени bin-base и размера группы (шага) bin-stride.

Каждая временная группа представляет собой отрезок времени и идентифицируется временем начала (time) этого отрезка, определяемого по формуле {time} = {bin-base} + {bin-stride} * i, где i — индекс временной группы.

Время начала "нулевой" группы (i=0) совпадает с bin-base. Индексы следующих (time > bin-base) и предыдущих (time < bin-base) временных групп соответственно увеличиваются или уменьшаются на единицу.

Во временную группу попадают события, произошедшие в момент времени (event-time) попадающий во временной отрезок группы: {time} ≤ {event-time} < {time} + {bin-stride}.

На основе данных из событий, попавших в каждую из временных групп, вычисляется производные значения, являющиеся значениями группы.

Дополнительные временные группы

Помимо множества групп, определяемых с помощью bin-base и bin-stride, для некоторых запросов статистики вычисляются значения дополнительных временных групп: BeforeFrom и AfterTo. В заданные группы попадают события, отфильтрованные с помощью параметров запросов from и to:

в BeforeFrom попадают события произошедшие ДО момента времени, указанного в from;
в AfterTo попадаю события произошедшие ПОСЛЕ момента времени, указанного в to.

Доступные типы статистики

На данный момент в системе поддерживаются несколько типов статистики.

Статистика общего количества предупреждений (total-invariants)

Определяет общее количество предупреждений (инвариантов), присутствующих в ветке при загрузке снимков (снапшотов) в течение определенного отрезка времени, разбитого на интервалы.

Для проекта: GET /api/projects/{project_id}/statistics/total-invariants

Для ветки: GET /api/projects/{project_id}/branch/{branch_id}/statistics/total-invariants

Данный тип статистики строится на основе количества предупреждений в снапшотов ветки, загружаемых в течение времени. Соответственно при попадании нескольких снапшотов (учитывается время импорта — import_time) в выбранной группе (например, неделя: 1w), будет выдана статистика с учётом нескольких снапшотов.

Для данного типа статистики, объект-значение (Value) состоит из полей:

Min — минимальное количество предупреждений, среди всех снапшотов, попавших в интервал
Max — максимальное количество предупреждений
Avg — среднее арифметическое количество предупреждений
Sum — сумма предупреждений, находящихся во всех снапшотов, попавших во временную группу (Sum / Avg = количество снапшотов в группе)

Для данного типа статистики, объект с дополнительными данными (Description) состоит из полей:

SnapshotNames — список строк с названиями снапшотов, попавших в описываемую временную группу

"TimeSerie": {
    "Items": [
        {
            "Time": "2023-04-03T00:00:00Z",
            "Value": {
                "Sum": 650,
                "Min": 300,
                "Max": 350,
                "Avg": 325
            },
            "Description": {
                "SnapshotNames": [
                    "Snapshot 2023-04-11 17:47:15 +0300",
                    "Snapshot 2023-04-11 17:49:25 +0300"
                ]
            }
        }, ...
    ]
}

Статистики размеченных предупреждений (activity)

Определяет количество предупреждений, для которых была произведена разметка в течение определенного отрезка времени, разбитого на интервалы

Для проекта: GET /api/projects/{project_id}/statistics/activity

Для ветки: GET /api/projects/{project_id}/branch/{branch_id}/statistics/activity

Данный тип статистики строится на основе количества активных (is_active) записей в group_review, имеющих статус НЕ Undecided. При этом подсчитывается количество предупреждений размеченных ДО и ПОСЛЕ выбранного отрезка времени. Также ведётся подсчёт общего количества предупреждений, размеченных в рамках выбранного отрезка времени. Для данного типа статистики {объект статистики ветки} содержит дополнительные поля:

BeforeFrom — количество предупреждений, размеченных ДО начала выбранного отрезка времени
AfterTo — количество предупреждений, размеченных ПОСЛЕ начала выбранного отрезка времени