5.7.3. TaskAlarms¶
Description¶
Downloading triggered alarms records for a particular task. In the Elecard Boro interface, triggers are configured on the Project settings page ➝ Notifications ➝ ALARMS. Triggered alarms can be found on the bottom of a task page in the TASK ALARMS tab.
Request¶
{
"user_id":(number),
"methods":[
{
"method":"TaskAlarms",
"params":{
"project_id":(number),
"task_id":(number),
"task_ids":' id1 | [id1,id2] | "*" '
"kind":(string),
"active_states_only":(boolean),
"limit_value":(number),
"page":(number),
"update_token":(number),
"filter":{
"period_from":(number),
"period_to":(number),
"level":(string),
"trigger_groups":[(string)],
"trigger_names": [(string)]
}
}
}
]
}
user_id - an integer value, a user identifier;
project_id - an integer value, a user project identifier;
task_id - an integer value, a task identifier. Deprecated, used for compatibility. If there are two fields with task identifiers, preference is given to the task_ids field;
- task_ids - task identifiers, the field can be specified in one of the following formats:
id1- an integer value, a task identifier;[id1,id2]- an array of integer values, task identifiers;"*"- a string, the “asterisk” symbol, information request for all active tasks of all running probes in the project. kind (optional field) - a string, a type of notification,
alarmis set by default. The current implementation only supports alarm notifications;active_states_only (optional field) - a logical type, if the
truevalue is transferred, records with active state errors will only be returned in a reply. Only for the State type triggers;limit_value (optional field) - an integer value, max number of records in a reply. It allows to paginate the results. The default value is 25, the max value is 100;
page (optional field) - an integer value, choosing a results page. The default value is 1. Not extended to a request with update_token;
update_token (optional field) - an integer value, a request key. To get records accumulated since the previous request, the key received in the last reply should be specified. The token is used to receive data only from the first page (max 100 records).
- filter (optional field) - an object, allows to perform advanced requests with additional parameters:
period_from - an integer value, time different from 0 in the Unix format. Specifies the requested period beginning;
period_to - an integer value, time in the Unix format. It must exceed period_from. Specifies the requested period ending;
level - a string, an error severity level. Available values are:
ok,warning,error,major,fatal;- trigger_groups - an array of strings, a group or several trigger groups. Available values are:
eth- Ethernet parameter triggers;etr- TR 101 290 error triggers;qoe- QoE parameter triggers;ott- OTT and Progressive Download services analysis triggers;sys- triggers referring to system errors in tasks;scte35- triggers referring to Ad insertion. trigger_names - an array of strings, a key name or several key names of triggers. The list of key names, examples of localized names in the Boro web interface and their descriptions are given in the table Trigger Description.
The trigger_groups and trigger_names fields are combined in a request by the logical “AND”. This should be noted while requesting since if the requested trigger is not included in the requested group, a reply will be empty.
The period_from and period_to fields specify the period of time in the records request. Both parameters or only one parameter can be set. It should be known that the updated_at field is processed during the SQL request (since the database is indexed for this field). Please note that the updated_at field value updates when the error disappears. For Event type triggers and active states, updated_at is equal to trigger_time.
Reply¶
{
"reply":[
{
"method":"TaskAlarms",
"result":{
"alarms":[
{
"id":(number),
"project_id":(number),
"app_id":(number),
"task_id":(number),
"profile_id":(number),
"trigger_time":(number),
"name":(string),
"level":(string),
"trigger_group":(string),
"type":(string),
"active":(boolean),
"kind":(string),
"info":{
...
"time":(number),
"time_end":(number)
}
}
],
"current_page":(number),
"limit_value":(number),
"total_pages":(number),
"update_token":(number)
}
}
]
}
alarms - an array of objects, records of triggered alarms;
id - an integer value, a record identifier;
project_id - an integer value, a user project identifier;
app_id - an integer value, a probe identifier;
task_id - an integer value, a task identifier;
profile_id - an integer value, a notification profile identifier (more information is in the section Profile Specific Methods);
trigger_time - an integer value, the creation time of a record (time of an alarm triggering) in the Unix time format. Since triggers are implemented on the server side, their processing time may significantly differs from time of a real event, e.g. as a result of a temporary loss of connection between the probe and the server. Herewith an event time or a state beginning and end time will be correctly saved in a record;
name - a string, a trigger key name. Key names are used for the interface localization. Examples of localized names in the Boro web interface and their descriptions are given in the table Trigger Description;
level - a string, an error severity level stated in trigger configurations. Available values are:
ok,warning,error,major,fatal;- trigger_group - a string, a group to which a record refers to:
eth- Ethernet parameter triggers;etr- TR 101 290 error triggers;qoe- QoE parameter triggers;ott- OTT and Progressive Download services analysis triggers;sys- triggers referring to system errors in tasks;scte35- triggers referring to Ad insertion. - type - a string, a trigger type:
state- triggers of the State type. Triggers of this type have a state beginning (triggering of a preset alarm) and state ending (when the error disappears). The current error state is returned in the active field. E.g. the BadSource (No signal) error state causes the alarm triggering in a set time and the state will remain active until the correct data appear on the analyser input;event- triggers of the Event type. The error occurrence is registered in a record (triggering of a preset alarm). E.g. when a segment cannot be downloaded, the error of the Event type occurs. - active - a logical type, a trigger current state. Only for the State type:
true- the error that was detected by the probe caused triggering of a preset alarm and the error state still remains active;false- the error disappeared. kind - a string, a notification type,
alarmis set by default. The current API implementation only supports alarm notifications;- info - an object, an event or state description. The object content differs for different trigger types:
time - a real number, an event or state beginning time. Time since a task start in seconds with a fractional part (to increase the accuracy);
time_end - a real number, a state ending time. Time since a task start in seconds with a fractional part (to increase the accuracy);
current_page - an integer value, a currently displayed page;
limit_value - an integer value, a max number of records in a reply;
total_pages - an integer value, a total number of result pages with limit_value specified;
update_token - an integer value, a request key. To get records accumulated since this request, the key received in the reply should be transferred in the next request.
A partial description of the triggered alarm advanced information:
{
"info":{
"count":(number),
"pids": {
"PIDn": {
"count": (number),
"type": (number),
"detectedType": (number),
"program": (string)
}
}
"event_data": {
"diff": [
...
]
...
}
"messages": [
{
"id": (number),
"params": {
...
}
"CURL_error": {
...
}
"HTTP_error": {
...
}
}
]
"time":(number),
"time_end":(number)
}
}
count - an integer value, a total sum of errors for all PIDs;
- pids - an object, a PID description, as well it may transfer error counters for each PID. Contains objects with a PID number conveyed as a field name:
- event_data - an object, contains the error description. May also include a reference to PID, error counters, the current metric state, the error information such as an HTTP status code or a curl detailed description, etc.
diff - an array of objects, changes in the JSON patch format. The format is extended with the prevValue field (next to the value field) for the change and remove operations. It is used for differences visualisation when a program description changes (ProgramSpecificInformation), a video stream description changes (VI_changed) or an audio stream description changes (AudioInformation_changed).
- messages - an array of objects, information messages which may include different parameters:
id - an integer value, a message identifier which is used for the localization. More information is in the table Table of Message Identifiers;
params - an object, message parameters.
CURL_error - an object, an error code, description and other details returned by the libcurl tool while analysing OTT services;
HTTP_error - an object, an error HTTP status code and other information for an OTT services analysis.
time - a real number, an event or state beginning time. Time since a task start in seconds with a fractional part (to increase the accuracy);
time_end - a real number, a real number, a state ending time. Time since a task start in seconds with a fractional part (to increase the accuracy).
Example¶
cURL utility¶ curl http://172.16.11.111/ctrl_api/v1/json \
-H "Content-Type: application/json" \
--data '{"user_id":4,"methods":[{"method":"TaskAlarms","params":{"project_id":23,"task_ids":241555,"limit_value":1}}]}'
{
"reply":[
{
"method":"TaskAlarms",
"result":{
"alarms":[
{
"id":13522793,
"project_id":23,
"app_id":702,
"task_id":241555,
"profile_id":390,
"trigger_time":1590570529,
"active":true,
"kind":"alarm",
"level":"warning",
"trigger_group":"qoe",
"type":"state",
"name":"AudioTrackMissing",
"info":{
"event_data":{
"pid":7010
},
"time":2322878.0005373
}
}
],
"current_page":1,
"limit_value":1,
"total_pages":1,
"update_token":1590592944
}
}
]
}