NAV
cURL JavaScript

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:

Optional parameter :

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:

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:

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

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:

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:

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:

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.