5.7.6. TaskKpiHistory¶
Description¶
Statistics about the number of registered errors, availability metrics and loss amount for a chosen time interval. The statistics include MLT/MLS parameters. The method is intended to generate reports about service quality.
Attention
Depending on the request depth, the number of tasks, and other factors, the response may take quite some time, i.e. tens of seconds. The method is intended to generate reports (seldom requests). To get statistics for the last 24 hours and for the last 15 minutes, use the TaskKpi method.
Request¶
{ "user_id":(number),
"methods":[{
"method":"TaskKpi",
"params":{
"project_id":(number),
"task_ids":' id1 | [id1,id2] | "*" ',
"period_from": (number),
"period_to": (number),
"interval": (number)}}]}
user_id — an integer representing a user ID;
project_id — an integer indicating a user’s project ID;
- task_ids — task IDs, a field in one of the following formats:
id1— an integer indicating a task ID;[id1,id2]— an array of integers representing task IDs;"*"— a string; an asterisk symbol means requesting information about all active tasks running on all probes in the project. period_from — an integer representing Unix time that is different from 0. It sets the beginning of the request period;
period_to — an integer indicating Unix time bigger than period_from. It sets the end of the request period;
interval (optional field) — an integer indicating an interval in minutes for getting all the statistics; the default interval value is 24 hours (1440 minutes). The field can take in a value between 15 and 1440 minutes; otherwise, the default interval is used, and the response will contain a warning.
Response¶
In the Boro system, all statistics are calculated as 15-minute (900 sec.) intervals that are saved to a database. 15-minute intervals can be combined in a bigger one, e.g., an hourly or daily report. This lets you retrieve information within the day’s range for different time zones, regardless of the server’s time zone. The interval field in the request sets the size of the intervals into which the data in the response will be split. The field value should be divisible by 15 minutes and fall within the range between 15 to 1440 minutes. If the value cannot be divided by 15 minutes, it is rounded down to a valid value. For example, 44 minutes are rounded down to 30 minutes.
The service availability data is returned as the combination of monitoring time + error seconds. You can find more information in the TaskKpi (Getting the Availability Metrics) method description.
{
"reply":[{
"method":"TaskKpiHistory",
"result":[
{
"task_id":(number),
"sections":[
[
"StartTime",
"MonitoringTime",
"Total",
"QOE",
"QOS",
"Alarms",
"States"
],
[
(number),
(number),
(number),
(number),
(number),
{
"Seconds":{
"ok":(number),
"warning":(number),
"error":(number),
"major":(number),
"fatal":(number),
"total":(number),
"badSource":(number),
"audioSilence":(number),
"videoFreeze":(number)
},
"Counts":{...}
},
{
"Seconds":{
"ok":(number),
"warning":(number),
"error":(number),
"major":(number),
"fatal":(number),
"total":(number),
"badSource":(number),
"audioSilence":(number),
"videoFreeze":(number)
"mlr":(number)
},
"Counts":{...}}]]}]}]}
task_id — an integer representing a task ID;
- sections — an object containing history for the period indicated in the request. The history is split into intervals. Metrics are returned as a table in the JSON format, where the first line contains table headers and the rest of the lines contain values:
StartTime — an integer showing Unix time that indicates the start of measuring each of the sections;
MonitoringTime — an integer showing the duration of monitoring within a certain section in seconds;
Total — an integer showing the total number of error seconds for all used key availability metrics in seconds;
QOE — an integer showing the error seconds for key QoE metrics in seconds;
QOS — an integer showing the error seconds for key QoS metrics in seconds.
- Alarms — an object containing information about the number of times triggers of different severity levels fired and their total duration. See the Alarms Statistics section in the KpiView chapter. The object can also contain individual statistics based on certain triggers:
- seconds — an object showing the duration of triggers that fired:
ok .. fatal — a real indicating the duration of triggers for each severity level in seconds;
total — a real representing the total duration of triggers of all severity levels in seconds;
badSource — a real indicating the duration of Bad Source trigger in seconds.
audioSilence — a real indicating the duration of Audio Silence trigger in seconds.
videoFreeze — a real indicating the duration of Video Freeze trigger in seconds.
- counts — an object showing the number of times the triggers fired:
ok .. fatal — an integer indicating the number of times the triggers of each severity level fired;
total — an integer representing the total number of times the triggers of all severity levels fired;
badSource — an integer showing the number of times the Bad Source trigger fired.
audioSilence — an integer showing the number of times the Audio Silence trigger fired.
videoFreeze — an integer showing the number of times the Video Freeze trigger fired.
- States — an object containing information about the number and duration of states/events received from the probe based on which the notification system generates alarms. This information is not provided in Boro on the KpiView ➝ Health tab except for key states (for example, Bad Source). The object also contains information about MLS/MLT metrics:
- seconds — an object showing the duration of states/events:
ok .. fatal — a real indicating the duration of states/events for each severity level in seconds. The severity level is taken from a setting of an alarm related to the event;
total — a real representing the total duration of states/events in seconds;
badSource — a real showing the duration of Bad Source state in seconds;
audioSilence — a real showing the duration of Audio Silence state in seconds;
videoFreeze — a real showing the duration of Video Freeze state in seconds;
mlr — a real indicating Media Loss Seconds, i.e. time in seconds during which the loss of packets for the last 15min/24h of monitoring was registered.
- counts — an object showing the number of states/events:
ok .. fatal — an integer indicating the number of states/events for each severity level. The severity level is taken from a setting of an alarm related to the event;
total — an integer showing the total number of states/events;
badSource — an integer showing the number of times the Bad Source state occurred;
audioSilence — an integer showing the number of times the Audio Silence state occurred;
videoFreeze — an integer showing the number of times the Video Freeze state occurred;
mlr — an integer indicating Media Loss Total, a total number of media packets lost during the last 15min/24h of monitoring.
Example¶
cURL utility¶#Requesting statistics history for one task with an interval of 24 hours.
#The request period is two days from "July 2, 2024, 00:00:00 GMT" to "July 4, 2024, 00:00:00 GMT"
curl http://172.16.11.111/ctrl_api/v1/json \
-H "Content-Type: application/json" \
--data '{"user_id":4,"methods":[{"method":"TaskKpiHistory","params":{"project_id":23,"task_ids":458684,"interval":1440,"period_from":1719878400,"period_to":1720051200}}]}'
{"reply":[{
"method":"TaskKpiHistory",
"result":[
{
"task_id":458684,
"sections":[
[
"StartTime",
"MonitoringTime",
"Total",
"QOE",
"QOS",
"Alarms",
"States"
],
[
1719878400,
86400,
13,
0,
13,
{
"Seconds":{
"ok":0,
"mlr":0,
"error":0,
"fatal":0,
"major":11.000505208969116,
"total":11.000505208969116,
"warning":0,
"audioSilence":0,
"videoFreeze": 0,
"badSource":3.8531429767608643
},
"Counts":{
"ok":0,
"error":0,
"fatal":0,
"major":8,
"total":8,
"warning":0,
"audioSilence":0,
"videoFreeze": 0,
"badSource":1
}
},
{
"Seconds":{
"ok":0,
"mlr":5,
"error":2.0011720657348633,
"fatal":0,
"major":68.51955962181091,
"total":73.52073168754578,
"warning":0,
"audioSilence":0,
"videoFreeze": 0,
"badSource":7.005940198898315
},
"Counts":{
"ok":0,
"mlr":81,
"error":1,
"fatal":0,
"major":43,
"total":44,
"warning":0,
"audioSilence":0,
"videoFreeze": 0,
"badSource":1
}
}
],
[
1719964800,
86400,
20,
0,
20,
{
"Seconds":{
"ok":0,
"mlr":0,
"error":0,
"fatal":0,
"major":14.47293734550476,
"total":14.47293734550476,
"warning":0,
"audioSilence":0,
"videoFreeze": 0,
"badSource":12.783230781555176
},
"Counts":{
"ok":0,
"error":0,
"fatal":0,
"major":2,
"total":2,
"warning":0,
"audioSilence":0,
"videoFreeze": 0,
"badSource":1
}
},
{
"Seconds":{
"ok":0,
"mlr":4,
"error":2.0013949871063232,
"fatal":0,
"major":69.75433158874512,
"total":73.75572657585144,
"warning":0,
"audioSilence":0,
"videoFreeze": 0,
"badSource":16.011757135391235
},
"Counts":{
"ok":0,
"mlr":57,
"error":1,
"fatal":0,
"major":34,
"total":35,
"warning":0,
"audioSilence":0,
"videoFreeze": 0,
"badSource":1}}]]}]}]}