Help:Statistics - Revision history

Akuzmin: change to reminder block

2024-06-19T12:12:38Z

change to reminder block

← Older revision		Revision as of 15:12, 19 June 2024
Line 8:		Line 8:
	* Для ветки: <code>GET /api/public/projects/{project_id}/branch/{branch_id}/statistics/{название типа статистики}</code>		* Для ветки: <code>GET /api/public/projects/{project_id}/branch/{branch_id}/statistics/{название типа статистики}</code>

	~~'''Внимание!'''~~ Как и для других типов запросов публичного REST API, в хедере запросов статистики необходимо передавать [[Help:Public_API#Получение_токена\|токен авторизации]] — <code>Authorization: Bearer <token></code>, полученный с помощью запроса к <code>/api/public/login</code>.		{{Note\|type=reminder\|text=Как и для других типов запросов публичного REST API, в хедере запросов статистики необходимо передавать [[Help:Public_API#Получение_токена\|токен авторизации]] — <code>Authorization: Bearer <token></code>, полученный с помощью запроса к <code>/api/public/login</code>}}

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

M.vinogradov at 07:08, 18 July 2023

2023-07-18T07:08:56Z

Akuzmin: minor layout fixes

2023-05-29T14:24:08Z

minor layout fixes

Show changes

Akuzmin: add category

2023-05-29T14:16:11Z

add category

← Older revision		Revision as of 17:16, 29 May 2023
Line 1:		Line 1:
	[[Category:Help]]		[[Category:Help]]

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

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

Akuzmin at 14:14, 29 May 2023

2023-05-29T14:14:41Z

← Older revision		Revision as of 17:14, 29 May 2023
Line 1:		Line 1:
			[[Category:Help]]

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

Akuzmin: minor fixes

2023-05-17T14:06:04Z

minor fixes

Show changes

M.vinogradov: Created page with "На данной странице приводится описание REST API загрузки статистики и доступные типы статистики. = Описание элементов REST API для загрузки статистики = Система поддерживает загрузку статистики для проектов и отдельных веток проектов: Для проекта: `GET /api/projects/{proj..."`


2023-05-17T13:01:06Z
Created page with "На данной странице приводится описание REST API загрузки статистики и доступные типы статистики.  = Описание элементов REST API для загрузки статистики =  Система поддерживает загрузку статистики для проектов и отдельных веток проектов:  Для проекта: <code>GET /api/projects/{proj..."
New page
На данной странице приводится описание REST API загрузки статистики и доступные типы статистики.



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



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



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



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



 '''Внимание!''' Как и для других типов запросов публичного REST API, в хедере запросов статистики необходимо передавать токен авторизации - <code>Authorization: Bearer <token></code> - полученный с помощью запроса к <code>/api/public/login</code> (см. [[Help:ServerClient#%D0%9F%D1%83%D0%B1%D0%BB%D0%B8%D1%87%D0%BD%D1%8B%D0%B5_REST_%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D1%8B|Публичные REST запросы]]).



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



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



{| class="wikitable"

|+ Caption text

|-

! Параметр !! Формат !! Значение по умолчанию !! Описание

|-

| from || время в одном из форматов поддерживаемых go || - || начало интересующего отрезка времени

|-

| to || время в одном из форматов поддерживаемых go || - || конец интересующего отрезка времени

|-

| bin-base || время в одном из форматов поддерживаемых go || <code>1970-01-01T00:00:00Z</code> || базовый момент времени, от которого отсчитываются временные группы

|-

| bin-stride || интервал времени, заданный с помощью строки вида <code>1y2M3w4d5h6m7s</code> || <code>1s</code> || размер временной группы (bin)

|}



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



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



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



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



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



* группа <code>val</code> - положительное целое число - количество временных единиц;

* группа <code>unit</code> - одна из букв 's'(секунды), 'm'(минуты), 'h'(часы), 'd'(дни), 'w'(недели), 'M'(месяцы), 'y'(годы) - тип временной единицы.



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



* <code>24h</code> - 24 часа

* <code>1m1m1m1m1m</code> - 5 минут

* <code>5d12h30m30s</code> - 5 дней + 12 часов + 30 минут + 30 секунд



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



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



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



 {

     "status": "OK",

     "result": {

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

     }

 }



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



 {

     "status": "OK",

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

 }



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



* <code>ContainerInfo</code> - информация о ветке;

** <code>ID</code> - uuid-идентификатор ветки

** <code>Name</code> - название ветки

** <code>Type</code> - int-идентификатор типа контейнера: для ветки всегда равен двум (2)

* <code>TimeSerie</code> - временной ряд, содержащий список временных групп, для которых были найдены события

** <code>Items</code> - список элементов временного ряда

*** <code>Time</code> - время начала временной группы (bin) в формате ISO 8601

*** <code>Value</code> - объект-значение с данными соответствующими типу статистики

*** <code>Description</code> (может отсутствовать) - дополнительные данные, относящиеся к переданному объекту-значению



 {

     "ContainerInfo": {

         "ID": "uuid-идентификатор ветки",

         "Name": "название ветки",

         "Type": 2

     },

     "TimeSerie": {

         "Items": [

             {

                 "Time": "2023-04-03T00:00:00Z",

                 "Value": {объект-значение с данными статистики},

                 "Description": {дополнительные данные}

             }, ...

         ]

     }

 }



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



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



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



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



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



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



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



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



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

* в <code>BeforeFrom</code> попадают события произошедшие ДО момента времени, указанного в <code>from</code>;

* в <code>AfterTo</code> попадаю события произошедшие ПОСЛЕ момента времени, указанного в <code>to</code>.



[[File:statistics-timing.png]]



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



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



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



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



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



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



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



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

* <code>Min</code> - минимальное количество предупреждений, среди всех снепшотов, попавших в интервал

* <code>Max</code> - максимальное количество предупреждений

* <code>Avg</code> - среднее арифметическое количество предупреждений

* <code>Sum</code> - сумма предупреждений, находящихся во всех снепшотах, попавших во временную группу (<code>Sum / Avg</code> = количество снепшотов в группе)



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

* <code>SnapshotNames</code> - список строк с названиями снепшотов, попавших в описываемую временную группу





 "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) ==



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



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



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



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

Для данного типа статистики {объект статистики ветки} содержит дополнительные поля:

* <code>BeforeFrom</code> - количество предупреждений, размеченных ДО начала выбранного отрезка времени

* <code>AfterTo</code> - количество предупреждений, размеченных ПОСЛЕ начала выбранного отрезка времени



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

* <code>Relative</code> - количество предупреждений, размеченных в указанной временной группе

* <code>Absolute</code> - количество предупреждений, размеченных с начала выбранного отрезка времени (сумма всех предшествующих <code>Relative</code>, включая текущий).



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



 "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

             }

         }, ...

     ]

 }

← Older revision		Revision as of 10:08, 18 July 2023
Line 5:		Line 5:
	Система поддерживает загрузку статистики для проектов и отдельных веток проектов:		Система поддерживает загрузку статистики для проектов и отдельных веток проектов:

	* Для проекта: <code>GET /api/projects/{project_id}/statistics/{название типа статистики}</code>		* Для проекта: <code>GET /api/public/projects/{project_id}/statistics/{название типа статистики}</code>
	* Для ветки: <code>GET /api/projects/{project_id}/branch/{branch_id}/statistics/{название типа статистики}</code>		* Для ветки: <code>GET /api/public/projects/{project_id}/branch/{branch_id}/statistics/{название типа статистики}</code>

	'''Внимание!''' Как и для других типов запросов публичного REST API, в хедере запросов статистики необходимо передавать [[Help:Public_API#Получение_токена\|токен авторизации]] — <code>Authorization: Bearer <token></code>, полученный с помощью запроса к <code>/api/public/login</code>.		'''Внимание!''' Как и для других типов запросов публичного REST API, в хедере запросов статистики необходимо передавать [[Help:Public_API#Получение_токена\|токен авторизации]] — <code>Authorization: Bearer <token></code>, полученный с помощью запроса к <code>/api/public/login</code>.
Line 125:		Line 125:
	Определяет общее количество предупреждений (инвариантов), присутствующих в ветке при загрузке снимков (снапшотов) в течение определенного отрезка времени, разбитого на интервалы.		Определяет общее количество предупреждений (инвариантов), присутствующих в ветке при загрузке снимков (снапшотов) в течение определенного отрезка времени, разбитого на интервалы.

	* Для проекта: <code>GET /api/projects/{project_id}/statistics/total-invariants</code>		* Для проекта: <code>GET /api/public/projects/{project_id}/statistics/total-invariants</code>
	* Для ветки: <code>GET /api/projects/{project_id}/branch/{branch_id}/statistics/total-invariants</code>		* Для ветки: <code>GET /api/public/projects/{project_id}/branch/{branch_id}/statistics/total-invariants</code>

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

	* Для проекта: <code>GET /api/projects/{project_id}/statistics/activity</code>		* Для проекта: <code>GET /api/public/projects/{project_id}/statistics/activity</code>
	* Для ветки: <code>GET /api/projects/{project_id}/branch/{branch_id}/statistics/activity</code>		* Для ветки: <code>GET /api/public/projects/{project_id}/branch/{branch_id}/statistics/activity</code>

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