Alarms on the Waylay platform are a way of tracking/following up on a condition/state of a resource.
Waylay Alarm service is at this URL: https://alarms.waylay.io
curl -i --user apiKey:apiSecret -H "Content-Type: application/json"
-X POST
-d '{
"type" : "io.waylay.alarm.test",
"timestamp" : "2011-09-06T12:03:27.845Z",
"text" : "Some alarm documentation",
"status" : "ACTIVE",
"severity" : "MAJOR",
"source" : { "id" : "12345", "self" : "..." }
"task" : 3425,
"myRef" : "902d4191-d1ab-47ae-8405-c33bb237f1d5"
}'
"https://alarms.waylay.io/alarm/alarms"
To create an alarm, you need to provide the following mandatory inputs:
type
: type of the alarmtext
: description of the alarmseverity
: any of CRITICAL
, MAJOR
, MINOR
or WARNING
source
: a JSON object with an id
field indicating the resourceOptional parameter :
status
: any of ACTIVE
, ACKNOWLEDGED
or CLEARED
(if not specified, created alarm will have status ACTIVE
)timestamp
: ISO date string or number (indicating milliseconds since epoch) (if not specified, timestamp will be set to the receive time)assignee
: string field to indicate an assignee for the alarmAny property in the creation json payload, that is not in the above mandatory or optional parameters will be saved in the additionalProperties
field of the created alarm
If an ACTIVE
or ACKNOWLEDGED
alarm with the same source.id
and type
exists, no new alarm is created. Instead, the existing alarm is updated
by incrementing the count
property and a new audit record of type io.waylay.alarm.EventOccuredAgain
is added to the history
.
Only the latest 1000 io.waylay.alarm.EventOccuredAgain
audit records are kept in the history
.
curl --user apiKey:apiSecret "https://alarms.waylay.io/alarm/alarms/02eee99c-cd32-4fd0-9a35-89fa15570ccc"
Will return something like
{
"id": "02eee99c-cd32-4fd0-9a35-89fa15570ccc",
"self": "/alarm/alarms/02eee99c-cd32-4fd0-9a35-89fa15570ccc",
"creationTime": "2017-09-12T15:23:33.075Z",
"type": "io.waylay.alarm.test",
"text": "Some alarm documentation",
"timestamp": "2017-09-12T15:23:33.074Z",
"source": {
"id": "bruno"
},
"severity": "MAJOR",
"status": "CLEARED",
"count": 1,
"assignee": "user/385bfb40-cb4d-4ad7-a306-fa6dc7152150",
"history": [
{
"id": "02114638-5d25-4031-b22a-40c883eb4c79",
"type": "io.waylay.alarm.AlarmRaised",
"text": "Alarm raised",
"timestamp": "2017-09-12T15:23:33.076Z"
},
{
"id": "03bd1347-6d2b-4d90-bdb1-1b44972af3d1",
"type": "io.waylay.alarm.AlarmUpdated",
"text": "Alarm updated",
"timestamp": "2017-09-23T11:18:56.358Z",
"changes": [
{
"attribute": "status",
"oldValue": "ACTIVE",
"newValue": "CLEARED",
"type": "io.waylay.alarm.change.status"
}
]
}
],
"additionalProperties": {
"task" : 3425,
"myRef" : "902d4191-d1ab-47ae-8405-c33bb237f1d5"
}
}
An alarm has following fields:
Name | Type | Description |
---|---|---|
id |
UUID | Uniquely identifies an alarm. |
self |
URI | Link to this alarm. |
creationTime |
ISO date string | Time when alarm was created in the database. |
type |
String | Identifies the type of this alarm. |
timestamp |
ISO date string | Time of the alarm. |
text |
String | Text description of the alarm |
source |
JSON Object | The resource that the alarm originated from, as object containing the “id” property. |
status |
String | The status of the alarm: ACTIVE , ACKNOWLEDGED or CLEARED . |
severity |
String | The severity of the alarm: CRITICAL , MAJOR , MINOR or WARNING . |
count |
Long | The number of times this alarm has been sent. |
assignee |
String | The assignee of the alarm, will not be present if there is no assignee |
history |
List of AuditRecord | History of modifications tracing property changes. |
additionalProperties |
JSON object | Additional properties that were present in the alarm creation JSON payload |
The history
keeps a record of changes that have happened to the alarm. There are 3 different types of changes:
io.waylay.alarm.AlarmRaised
: creation of the alarmio.waylay.alarm.EventOccuredAgain
: a request to create an alarm happened, but an alarm of the same type
in status ACTIVE
or ACKNOWLEDGED
existed
on the same source
object at that moment (Remark: only the latest 1000 audit records of this type are kept in the history
)io.waylay.alarm.AlarmUpdated
: some attribute(s) of the alarm where updated. The audit record will contain a list of changes
that happened.curl -i --user apiKey:apiSecret -H "Content-Type: application/json"
-X PUT
-d '{
"severity" : "minor",
"status" : "acknowledged",
"assignee" : "user/385bfb40-cb4d-4ad7-a306-fa6dc7152150"
}'
"https://alarms.waylay.io/alarm/alarms/02eee99c-cd32-4fd0-9a35-89fa15570ccc"
Only severity
, status
and assignee
can be updated. At least one field must be specified.
You can only update an ACTIVE
or ACKNOWLEDGED
alarm. Updating a CLEARED
alarm will result in a response code 412 Precondition Failed
Clearing the assignee
can be done by either setting it to the empty string (""
) or null
Please notice that if the update actually doesn’t change anything (i.e. request body contains data that is identical to already present data in the database), there will be no audit record added.
curl --user apiKey:apiSecret
-X DELETE "https://alarms.waylay.io/alarm/alarms/02eee99c-cd32-4fd0-9a35-89fa15570ccc"
Alarms (even alarms in ACTIVE
or ACKNOWLEDGED
status) are only kept in the system for one year after creation.
Any alarm older then 1 year is automatically deleted.
curl --user apiKey:apiSecret "https://alarms.waylay.io/alarm/alarms"
This above call gives the first 50 alarms. If you need to filter the alarms, you can use a query language
curl --user apiKey:apiSecret
"https://alarms.waylay.io/alarm/alarms?source=6&status=ACTIVE&status=CLEARED"
This would give you a result like
{
"self": "/alarm/alarms?status=ACTIVE&status=CLEARED&source=6",
"next": "/alarm/alarms?status=ACTIVE&status=CLEARED&source=6&page=2",
"total": 361,
"alarms": [
{
"id": "586ac2f2-fbec-426a-b696-d63d6cb153ac",
"self": "/alarm/alarms/586ac2f2-fbec-426a-b696-d63d6cb153ac",
"creationTime": "2017-08-23T11:16:37.856Z",
"type": "alarmtest",
"text": "Another test alarm",
"timestamp": "2017-08-23T11:16:08Z",
"source": {
"stuff": "blabla",
"id": "6"
},
"severity": "MINOR",
"status": "CLEARED",
"count": 1,
"history": [
{
"id": "54597bdb-7409-4c47-b7ba-f08922b67ca2",
"type": "io.waylay.alarm.AlarmRaised",
"text": "Alarm raised",
"timestamp": "2017-08-23T11:16:37.856Z"
},
{
"id": "03bd1347-6d2b-4d90-bdb1-1b44972af3d1",
"type": "io.waylay.alarm.AlarmUpdated",
"text": "Alarm updated",
"timestamp": "2017-08-23T11:18:56.358Z",
"changes": [
{
"attribute": "status",
"oldValue": "ACTIVE",
"newValue": "CLEARED",
"type": "io.waylay.alarm.change.status"
}
]
}
]
},
{
"id": "df036bf8-4b32-4bd8-8ee7-42800ab26bf5",
"self": "/alarm/alarms/df036bf8-4b32-4bd8-8ee7-42800ab26bf5",
"creationTime": "2017-08-18T15:54:51.180Z",
"type": "alarmType",
"text": "Another test alarm",
"timestamp": "2009-02-13T23:31:30.128Z",
"source": {
"id": "6"
},
"severity": "MAJOR",
"status": "ACTIVE",
"count": 2,
"history": [
{
"id": "e64de65c-e3ef-482d-9eb7-32ca17d1e147",
"type": "io.waylay.alarm.AlarmRaised",
"text": "Alarm raised",
"timestamp": "2017-08-18T15:54:51.183Z"
},
{
"id": "b708f1e2-9da4-442b-ac6c-0120b0b11c08",
"type": "io.waylay.alarm.EventOccuredAgain",
"text": "Alarm event occured again",
"timestamp": "2017-08-21T07:26:47.209Z"
}
]
},
...
}
You can also query for alarms
Query criteria can be specified in the query string. Available criteria:
type
: filter on typestatus
: filter on statusseverity
: filter on severitysource
: filter on id of the sourcedateFrom
: long (milliseconds since epoch) to filter on timestamp ( >= dateFrom)dateTo
: long (milliseconds since epoch) to filter on timestamp ( <= dateTo)assignee
: filter on assigneeDifferent query parameters are combined with logical AND operator. Specifying the same query parameter (only for type
, status
, severity
and source
) more then once,
will be handled with a logical OR operation.
That means that if you combine e.g. status
and source
parameter, you will get only alarms on the specified source
with the given status
,
but if you specify e.g. status
twice (like status=ACTIVE&status=ACKNOWLEDGED
) you will get all ACTIVE
and ACKNOWLEDGED
alarms
Paging is also supported through the query string with following options (results are sorted by descending timestamp
):
page
: page number (default: 1)size
: size of a page (default: 50)The response does contain total
number of alarms that fullfill the criteria. Also the response contains links to the current page self
,
to the next
page if there is a next page and the previous
page if there is one.
To query the alarms based on the value of an additional property of the alarm, you can add the key of the additional property as query parameter with value the value you expect the alarm to have.
Query for ACTIVE alarms with additional property task=3425
curl --user apiKey:apiSecret
"https://alarms.waylay.io/alarm/alarms?status=ACTIVE&task=3425"
curl --user apiKey:apiSecret \
-H 'Accept: application/vnd.waylay.alarms.timeseries+json' \
"https://alarms.waylay.io/alarm/alarms?source=6&status=ACTIVE&status=CLEARED"
This would give you a result like
[
{
"timestamp": 1503486997856,
"type": "io.waylay.alarm.AlarmRaised",
"alarm": {
"id": "586ac2f2-fbec-426a-b696-d63d6cb153ac",
"creationTime": "2017-08-23T11:16:37.856Z",
"timestamp": "2017-08-23T11:16:08Z",
"source": {
"stuff": "blabla",
"id": "6"
},
"type": "alarmtest",
"text": "Another test alarm",
"severity": "MINOR",
"status": "ACTIVE",
}
},
{
"timestamp": 1503487136358,
"type": "io.waylay.alarm.AlarmUpdated",
"alarm": {
"id": "586ac2f2-fbec-426a-b696-d63d6cb153ac",
"creationTime": "2017-08-23T11:16:37.856Z",
"timestamp": "2017-08-23T11:16:08Z",
"source": {
"stuff": "blabla",
"id": "6"
},
"type": "alarmtest",
"text": "Another test alarm",
"severity": "MINOR",
"status": "CLEARED",
}
},
...
]
It is possible to get the alarm history information on one or more source object as a timeline.
To do so, you call the Query multiple alarms endpoint specifying at least one source
id
and you set the Accept
http header to application/vnd.waylay.alarms.timeseries+json
.
The response will be a JSON array of objects with following keys:
timestamp
(number): timestamp in epochmillistype
(string): type of the history event - see Alarm eventsalarm
(object): alarm information (including id
, source id
, severity
and status
) the alarm had at the timestamp
When querying the alarms as a timeline you can limit the returned timeframe
by using query parameters from
and/or to
(both as a number as epochmillis).
Any paging parameters (page
and/or size
) are ignored if you query the alarms as a timeline
Posting an operation to delete alarms in batch
curl --user apiKey:apiSecret \
-X POST "https://alarms.waylay.io/batch" \
-H "Content-Type:application/json" \
-d '{
"entity": "alarm",
"action": "delete",
"query" : {
"ids" : [
"586ac2f2-fbec-426a-b696-d63d6cb153ac",
"df036bf8-4b32-4bd8-8ee7-42800ab26bf5",
"e64de65c-e3ef-482d-9eb7-32ca17d1e147"
]
}
}'
The batch endpoint /batch
allows you to post an operation to multiple alarms.
This operation will be executed asynchronously.
When posting an operation, you need to specify the action
and the type of entities you want the operation to act on.
For the alarm service this is always alarm
.
You also specify a query
that selects the entities and potentially (dependent on the action) also some parameters specific for the action.
Result of above call
{
"statusCode": 202,
"uri": "/batch/afcea5a1-81df-44f6-bd34-e0b602a2cf3d",
"entity": {
"id": "afcea5a1-81df-44f6-bd34-e0b602a2cf3d",
"queueTime": "2020-04-27T09:54:44.051Z",
"operation": {
"entity": "alarm",
"action": "delete"
}
}
}
When posting an operation, the batch endpoint will return an url
which you can use to retrieve (GET
) the status and results of the operation.
Result of
GET https://alarms.waylay.io/batch/afcea5a1-81df-44f6-bd34-e0b602a2cf3d
{
"id": "afcea5a1-81df-44f6-bd34-e0b602a2cf3d",
"user": "22f6dfdf-a50c-4eab-953e-8d2e56891dbe",
"operation": {
"entity": "alarm",
"action": "delete",
"description": "deleting 3 alarms"
},
"queueTime": "2020-04-27T09:54:44.051Z",
"finishedTime": "2020-04-27T09:54:44.129Z",
"results": {
"success": {
"df036bf8-4b32-4bd8-8ee7-42800ab26bf5": {
"statusCode": 204
}
},
"failure": {
"586ac2f2-fbec-426a-b696-d63d6cb153ac": {
"statusCode": 404,
"error": "alarm with id '586ac2f2-fbec-426a-b696-d63d6cb153ac' not found"
},
"e64de65c-e3ef-482d-9eb7-32ca17d1e147": {
"statusCode": 404,
"error": "alarm with id 'e64de65c-e3ef-482d-9eb7-32ca17d1e147' not found"
}
}
}
}
When retrieving the status of the bulk operation (using the url from the response of the POST
call),
the response will contain the finishedTime
when the operation has completely finished and a results
object that has
success
and failure
fields indicating (per queried entity if possible, else on a generic key), a statusCode
and, for failure an error
message.
Below you can find the supported bulk actions on alarms
You can delete multiple alarms by specifying alarm ids
in the query object.
Bulk delete of alarm by specifying ids
curl --user apiKey:apiSecret \
-X POST "https://alarms.waylay.io/batch" \
-H "Content-Type:application/json" \
-d '{
"entity": "alarm",
"action": "delete",
"query" : {
"ids" : [
"586ac2f2-fbec-426a-b696-d63d6cb153ac",
"df036bf8-4b32-4bd8-8ee7-42800ab26bf5",
"e64de65c-e3ef-482d-9eb7-32ca17d1e147"
]
}
}'
Bulk delete of alarm by specifying query filters
curl --user apiKey:apiSecret \
-X POST "https://alarms.waylay.io/batch" \
-H "Content-Type:application/json" \
-d '{
"entity": "alarm",
"action": "delete",
"query" : {
"source": "6",
"severity": [
"MINOR",
"WARNING"
]
}
}'
Or you can use the same as the filters for querying the alarms (see above).
For the type
, status
, severity
and source
filters, you can either specify 1 value (as string)
or an array
of values.
For dateFrom
, dateTo
and assignee
filters, you can only specify 1 value
curl --user apiKey:apiSecret \
-X POST "https://alarms.waylay.io/batch" \
-H "Content-Type:application/json" \
-d '{
"entity": "alarm",
"action": "update",
"query" : {
"ids" : [
"586ac2f2-fbec-426a-b696-d63d6cb153ac",
"df036bf8-4b32-4bd8-8ee7-42800ab26bf5",
"e64de65c-e3ef-482d-9eb7-32ca17d1e147"
]
},
"actionParameters" : {
"status" : "ACKNOWLEDGED"
}
}'
You can update multiple alarms by specifying alarm ids
in the query object.
Next in the actionParameters
object you specify at least one of the following fields to update:
severity
status
assignee
Get application/x-ndjson stream of alarm events
curl --user apiKey:apiSecret
"https://alarms.waylay.io/alarm/events"
{
"eventtype": "io.waylay.alarm.AlarmRaised",
"eventtime": "2019-03-01T10:07:58.772962Z",
"alarm": {
"id": "f8c692cf-80f7-4ade-a0e2-3d3586b64ba0",
"creationTime": "2019-03-01T10:07:58.772958Z",
...
}
}
\n
{
"eventtype": "io.waylay.alarm.EventOccuredAgain",
"eventtime": "2019-03-01T10:07:55.960860Z",
"alarm": {
"id": "9f2b01b4-5932-4d43-b7fe-e18aae47a93d",
"creationTime":
...
}
}
\n
{
"eventtype": "io.waylay.alarm.AlarmUpdated",
"eventtime": "2019-03-01T10:07:55.963025Z",
"alarm": {
"id": "ab4d4695-82c6-4eb5-9615-80d9f7cdbd68",
...
},
"changes": [
{
"attribute": "status",
"oldValue": "ACTIVE",
"newValue": "CLEARED",
"type": "io.waylay.alarm.change.status"
}
]
}
\n
...
You can listen for events on alarm.
Each event contains the eventtype
, an eventtime
and the alarm
(with reduced properties) on which the event happened.
Possible eventtype
s:
io.waylay.alarm.AlarmRaised
: a new alarm was createdio.waylay.alarm.EventOccuredAgain
: an alarm happened againio.waylay.alarm.AlarmUpdated
: an alarm was updatedIn case the event is a io.waylay.alarm.AlarmUpdated
event, the event will also contain a changes
property that indicates what properties of the alarm changed.