Help:Statistics

From Svacer Wiki

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

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

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

  • Для проекта: GET /api/public/projects/{project_id}/statistics/{название типа статистики}
  • Для ветки: GET /api/public/projects/{project_id}/branch/{branch_id}/statistics/{название типа статистики}
Внимание! Как и для других типов запросов публичного REST API, в хедере запросов статистики необходимо передавать токен авторизации — Authorization: Bearer <token>, полученный с помощью запроса к /api/public/login.

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

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

Параметр Формат Значение по умолчанию Описание
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/public/projects/{project_id}/statistics/total-invariants
  • Для ветки: GET /api/public/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/public/projects/{project_id}/statistics/activity
  • Для ветки: GET /api/public/projects/{project_id}/branch/{branch_id}/statistics/activity

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

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

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

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

Для данного типа статистики, объект с дополнительными данными (Description) отсутствует. 

"BeforeFrom": 100,
"AfterTo": 15,
"TimeSerie": {
    "Items": [
        {
            "Time": "2023-04-01T12:00:00Z",
            "Value": {
                "Relative": 2,
                "Absolute": 2
            }
        },
        {
            "Time": "2023-04-01T13:00:00Z",
            "Value": {
                "Relative": 1,
                "Absolute": 3
            }
        }, ...
    ]
}
Retrieved from "https://svacer.ispras.ru/mediawiki/index.php?title=Help:Statistics&oldid=1110"