Query the system for information about current and past alerts

GET

http://os-992244000006.local/api/v1/sensor/alerts

GET

/api/v1/sensor/alerts

$ curl http://os-992244000006.local/api/v1/sensor/alerts

1 {
2   "log": [
3     {
4       "active": true,
5       "category": "OVERTEMP",
6       "cursor": 1024,
7       "id": "ERR_OVR_TMP_01",
8       "level": "ERROR",
9       "msg": "Sensor temperature exceeded safe threshold",
10       "msg_verbose": "The internal temperature sensor reading reached 95°C, exceeding the maximum operating temperature of 85°C. Immediate cooling required to prevent damage.",
11       "realtime": "1687804800.123456"
12     },
13     {
14       "active": false,
15       "category": "OVERTEMP",
16       "cursor": 1025,
17       "id": "ERR_OVR_TMP_01",
18       "level": "ERROR",
19       "msg": "Sensor temperature back to normal",
20       "msg_verbose": "The internal temperature sensor reading dropped below 85°C, alert cleared.",
21       "realtime": "1687808400.654321"
22     }
23   ],
24   "next_cursor": 1026,
25   "active": [
26     {
27       "active": true,
28       "category": "INPUT_VOLTAGE",
29       "cursor": 1026,
30       "id": "WARN_VOLT_LOW",
31       "level": "WARNING",
32       "msg": "Input voltage below recommended level",
33       "msg_verbose": "The sensor input voltage dropped to 10.5V, below the recommended minimum of 11V. Check power supply.",
34       "realtime": "1687812000.789012"
35     }
36   ]
37 }

Sensor diagnostic information.

Two lists will be returned, an active list and a log list. The active list contains a list of currently active events. The number of events in the active event list is unlimited.

The log list will contain all alert trigger and clear events. An alert-clear event has the same attributes and values as its corresponding trigger event, apart from the realtime and cursor attributes which will have increased, since an alert-clear event will always be received after an alert-trigger event. The log list has a length limit of 32 events in the form of a FIFO (First in First Out) queue. When the log list length limit is reached and a new event is added, the oldest event is deleted.

In addition to the active and log lists, GET /api/v1/sensor/alerts also returns a next_cursor field. Every alert event has a cursor attribute, which increments for every alert event logged. This can be used to track the alert activity that has been viewed and reduce message bandwidth. To do this, users are recommended to save the next_cursor field when calling GET /api/v1/sensor/alerts and then to use that value as the cursor argument on the next GET /api/v1/sensor/alerts call to fetch only new log entries.

Additional Information:

The cursor will wrap at 2^32 entries. It is important to understand the behavior during the wrap case, since this may lead to some unexpected consequences:

If cursor < (next_cursor - 32) % 2^32 then some entries may be filtered. For instance if cursor =0 and next_cursor =0 no entries will be reported immediately after cursor wrap, even though the log contains 32 entries, where submitting cursor =4294967264 (next_cursor - 32) % 2^32 will return all logged values.
If cursor > next_cursor all 32 entries will be reported. The recommended approach to using the interface is to always base queries on the previous value of next_cursor

Sensor diagnostic information. Two lists will be returned, an __active__ list and a __log__ list. The __active__ list contains a list of currently active events. The number of events in the __active__ event list is unlimited. The __log__ list will contain all alert trigger and clear events. An alert-clear event has the same attributes and values as its corresponding trigger event, apart from the realtime and __cursor__ attributes which will have increased, since an alert-clear event will always be received after an alert-trigger event. The __log__ list has a length limit of 32 events in the form of a FIFO (First in First Out) queue. When the __log__ list length limit is reached and a new event is added, the oldest event is deleted. In addition to the __active__ and __log__ lists, `GET /api/v1/sensor/alerts` also returns a __next_cursor__ field. Every alert event has a __cursor__ attribute, which increments for every alert event logged. This can be used to track the alert activity that has been viewed and reduce message bandwidth. To do this, users are recommended to save the __next_cursor__ field when calling `GET /api/v1/sensor/alerts` and then to use that value as the __cursor__ argument on the next `GET /api/v1/sensor/alerts` call to fetch only new __log__ entries. __Additional Information:__ The __cursor__ will wrap at 2^32 entries. It is important to understand the behavior during the wrap case, since this may lead to some unexpected consequences: * If __cursor__ < (__next_cursor__ - 32) % 2^32 then some entries may be filtered. For instance if __cursor__ =0 and __next_cursor__ =0 no entries will be reported immediately after __cursor__ wrap, even though the log contains 32 entries, where submitting __cursor__ =4294967264 (next_cursor - 32) % 2^32 will return all logged values. * If __cursor__ > __next_cursor__ all 32 entries will be reported. The recommended approach to using the interface is to always base queries on the previous value of __next_cursor__

Query parameters

cursorintegerOptional

Filters the alerts to only those with cursor >= query-value

modeenumOptional

Specifies the query mode

Allowed values:

Response

Successful operation

loglist of objects

A log of all alerts that have occurred since the sensor was last initialized

next_cursorinteger>=0

Indicates the cursor value that will occur in the next alert to fire

activelist of objects

A filtered version of log that lists only those alerts that are currently active

Errors

400

Bad Request Error

500

Internal Server Error