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.

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:

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.

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

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.