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.

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 a single alarm

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

Deletion of alarms in bulk

curl --user apiKey:apiSecret
  -X DELETE "https://alarms.waylay.io/alarm/alarms?source=..."

You can delete multiple alarms by specifying at least one filter in the query string. The possible filters are the same as the filters for quering the alarms (see below): type, status, severity, source, dateFrom, dateTo, assignee

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.

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:

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

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.