5.7.5. TaskKpi

Description

Statistics about the number of registered errors, availability metrics and loss amount for the last 24 hours and for the last 15 minutes. The statistics include MLT/MLS parameters. This method allows you to get the majority of data that can be found in the KpiView ➝ Health tab (a detailed description of received data).

Request

{ "user_id":(number),
  "methods":[{
      "method":"TaskKpi",
      "params":{
        "project_id":(number),
        "task_ids":' id1 | [id1,id2] | "*" '
        "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.

  • interval (optional field) — an integer indicating an interval in minutes for getting statistics about service availability; the default interval value is 2 hours (120 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. More details are available in the section below.

Getting the Availability Metrics

Service availability is a statistic parameter that is a numeric expression of the provided service quality. The availability formula is given in the ANSI/SCTE 168-6 recommendation:

\[Availability\,(\%) = \frac{Monitoring\,Time - Error\,Seconds}{Monitoring\,Time} \times 100\%\]

where:

  • Monitoring Time — time of monitoring;

  • Error Seconds — the number of error seconds detected during monitoring time.

The formula factors in the monitoring time but not the service provision time, because the presence or absence of errors in a service can be identified reliably only when monitoring this service. In the Boro system, availability is calculated as 15-minute (900 sec.) intervals, the results of which are saved to a database. 15-minute intervals can be combined in a bigger one, e.g., an hourly or daily report. You can find more information in the User Guide

The interval field in the request sets the size of the intervals into which service availability data for the last 24 hours of monitoring 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.

This way you can get data for building both trend mini graphs and detailed availability graphs. The representation examples can be found in the KpiView ➝ Health tab (see the Service Availability section).

Response

{"reply":[{
    "method":"TaskKpi",
    "result":[
      {
        "task_id":(number),
        "alarms_stat":{
          "15min":{
            "seconds":{
              "ok":(number),
              "warning":(number),
              "error":(number),
              "major":(number),
              "fatal":(number),
              "total":(number),
              "badSource":(number),
              "audioSilence":(number),
              "videoFreeze":(number)
            },
            "counts":{...},
            "actualWindowSize":(number)
          },
          "24h":{
            "seconds":{...},
            "counts":{...},
            "actualWindowSize":(number)
          }
        },
        "states_stat":{
          "15min":{
            "seconds":{
              "ok":(number),
              "warning":(number),
              "error":(number),
              "major":(number),
              "fatal":(number),
              "total":(number),
              "badSource":(number),
              "audioSilence":(number),
              "videoFreeze":(number)
              "mlr":(number)
            },
            "counts":{...},
            "actualWindowSize":(number)
          },
          "24h":{
            "seconds":{...},
            "counts":{...},
            "actualWindowSize":(number)
          }
        },
        "kpi_stat":{
          "15min":{
            "QOS":(number),
            "QOE":(number),
            "Total":(number),
            "MonitoringTime":(number)
          },
          "24h":{...},
          "sections":[
            [
              "StartTime",
              "MonitoringTime",
              "Total",
              "QOE",
              "QOS"
            ],
            [
              (number),
              (number),
              (number),
              (number),
              (number)]]}}]}]}

  • task_id — an integer representing a task ID;

  • alarms_stat — an object containing information about the number of times the 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:
    • 15min and 24h — objects representing intervals for measuring alarm statistics. The statistics are collected using the sliding window technique:
      • seconds — an object showing the duration of triggers that fired within the measurement interval:

        • 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 during the measurement interval:

        • 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 indicating the number of times the Bad Source trigger fired.

        • audioSilence — an integer indicating the number of times the Audio Silence trigger fired.

        • videoFreeze — an integer indicating the number of times the Video Freeze trigger fired.

    • actualWindowSize — a real showing the actual monitoring time on 15min/24h intervals in seconds. It can be different from 15min/24h when the task has just been started; the task was stopped/crashed for a short period or there was a loss of connection with the probe.

  • states_stat — an object that contains 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:
    • 15min and 24h — objects representing intervals for measuring the statistics of states/events and MLS/MLT. The statistics are collected using the sliding window technique:
      • seconds — an object showing the duration of states/events on the measurement interval:

        • 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 on the measurement interval:

        • 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.

    • actualWindowSize — a real showing the actual monitoring time on the 15min/24h intervals in seconds. It can be different from 15min/24h when the task has just been started; the task was stopped/crashed for a short period or there was a loss of connection with the probe.

  • kpi_stat — an object containing information about service availability. See the Service Availability section in the KpiView chapter:
    • 15min and 24h — objects indicating intervals for measuring statistics about service availability. The statistics are collected using the sliding window technique:

      • QOS — an integer showing the error seconds for key QoS metrics in seconds;

      • QOE — an integer showing the error seconds for key QoE metrics in seconds;

      • Total — an integer showing the error seconds for all used key availability metrics in seconds;

      • MonitoringTime — an integer showing the monitoring duration on the chosen interval in seconds.

    • sections — an object representing the service availability for the last 24 hours of monitoring split into sections for displaying on graphs or trends. For more details, see the request description in the Getting the Availability Metrics section. 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.

Example

A request with the cURL utility
#Requesting statistics for one task with splitting KPI for 4 intervals

  curl http://172.16.11.111/ctrl_api/v1/json \
   -H "Content-Type: application/json" \
   --data '{"user_id":4,"methods":[{"method":"TaskKpi","params":{"project_id":23,"task_ids":458684,"interval":360}}]}'
A response to the request
 {
 "reply":[
   {
     "method":"TaskKpi",
     "result":[
       {
         "task_id":458684,
         "alarms_stat":{
           "15min":{
             "seconds":{
               "major":0,
               "fatal":0,
               "total":0,
               "badSource":0,
               "audioSilence": 0,
               "videoFreeze": 0,
               "warning":0,
               "error":0,
               "ok":0
             },
             "counts":{
               "error":0,
               "badSource":0,
               "audioSilence": 0,
               "videoFreeze": 0,
               "warning":0,
               "fatal":0,
               "total":0,
               "major":0,
               "ok":0
             },
             "actualWindowSize":893.9871234893799
           },
           "24h":{
             "seconds":{
               "mlr":0,
               "error":0,
               "fatal":0,
               "major":10.103976011276245,
               "total":10.103976011276245,
               "warning":0,
               "badSource":5.190662622451782,
               "audioSilence": 0,
               "videoFreeze": 0,
               "ok":0
             },
             "counts":{
               "error":0,
               "fatal":0,
               "major":5,
               "total":5,
               "warning":0,
               "badSource":2,
               "audioSilence": 0,
               "videoFreeze": 0,
               "ok":0
             },
             "actualWindowSize":86400
           }
         },
         "states_stat":{
           "15min":{
             "seconds":{
               "warning":0,
               "major":0,
               "total":0,
               "mlr":0,
               "ok":0,
               "error":0,
               "fatal":0,
               "audioSilence": 0,
               "videoFreeze": 0,
               "badSource":0
             },
             "counts":{
               "error":0,
               "total":0,
               "mlr":0,
               "major":0,
               "warning":0,
               "audioSilence": 0,
               "videoFreeze": 0,
               "badSource":0,
               "fatal":0,
               "ok":0
             },
             "actualWindowSize":893.9871234893799
           },
           "24h":{
             "seconds":{
               "mlr":6.991044521331787,
               "error":2.0011396408081055,
               "fatal":0,
               "major":92.99074816703796,
               "total":96.98152017593384,
               "warning":0,
               "badSource":13.008315324783325,
               "audioSilence": 0,
               "videoFreeze": 0,
               "ok":0
             },
             "counts":{
               "badSource":2,
               "audioSilence": 0,
               "videoFreeze": 0,
               "ok":0,
               "mlr":80,
               "error":1,
               "fatal":0,
               "major":50,
               "warning":0,
               "total":51
             },
             "actualWindowSize":86400
           }
         },
         "kpi_stat":{
           "15min":{
             "Total":0,
             "QOS":0,
             "QOE":0,
             "MonitoringTime":900
           },
           "24h":{
             "MonitoringTime":85500,
             "Total":18,
             "QOE":0,
             "QOS":18
           },
           "sections":[
             [
               "StartTime",
               "MonitoringTime",
               "Total",
               "QOE",
               "QOS"
             ],
             [
               1718789400,
               21600,
               0,
               0,
               0
             ],
             [
               1718811000,
               21600,
               0,
               0,
               0
             ],
             [
               1718832600,
               21600,
               18,
               0,
               18
             ],
             [
               1718854200,
               20700,
               0,
               0,
               0]]}}]}]}