Alarms

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

Create an alarm

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 alarm
text: description of the alarm
severity: any of CRITICAL, MAJOR, MINOR or WARNING
source: a JSON object with an id field indicating the resource

Optional 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 alarm

Any 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 countproperty 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.

Get an alarm

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 alarm
io.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.

Update an alarm

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.

Deletion of an alarm

curl --user apiKey:apiSecret
  -X DELETE "https://alarms.waylay.io/alarm/alarms/02eee99c-cd32-4fd0-9a35-89fa15570ccc"

Automatic deletion of alarms

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.

Query multiple alarms

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 type
status: filter on status
severity: filter on severity
source: filter on id of the source
dateFrom: long (milliseconds since epoch) to filter on timestamp ( >= dateFrom)
dateTo: long (milliseconds since epoch) to filter on timestamp ( <= dateTo)
assignee: filter on assignee

Different 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"

Query alarms as a timeline

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 epochmillis
type (string): type of the history event - see Alarm events
alarm (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

Batch alarm operations

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

Deletion of alarms in bulk

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

Update of alarms in bulk

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

Alarm events

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 eventtypes:

io.waylay.alarm.AlarmRaised: a new alarm was created
io.waylay.alarm.EventOccuredAgain: an alarm happened again
io.waylay.alarm.AlarmUpdated: an alarm was updated

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