Skip to content

Latest commit

 

History

History
127 lines (87 loc) · 4.64 KB

Alarms.md

File metadata and controls

127 lines (87 loc) · 4.64 KB
Raw

Alarms api

Your containers will automatically generate alarms on critical conditions, those alarms, in addition to being showed via jabber or console, are stored in a database to be easily retrieved via the api.

The amount of alarms to be stored is limited by default to 100 per container (but you can ask your supplier to increase them).

To access the list of stored alarms you call /alarms/:

curl https://kratos:[email protected]/api/alarms/

Alarms fields

Each alarm entry exposes the following fields/attributes:

  • id (the unique identifier of the alarm)
  • container (the uid of the container generating the alarm, required)
  • level (identify the type of the alarm, there is a pre-defined list of levels, see below)
  • color (a user-defined color in the form #rrggbb, can be used by api GUI)
  • class (a user-defined class for the alarm)
  • vassal (a user-defined value for the vassal generating the alarm)
  • line (the line of code generating the error, useful for storing exceptions)
  • filename (the filename generating the error, useful for storing exceptions)
  • func (the function generating the error, useful for storing exceptions)
  • unix (the unix time of the alarm, required)
  • msg (the body of the alarm, required)

Alarms levels

Currently the following 'levels' are defined. They are conventions (they are effectively simple positive numbers), that can be used in GUIs:

  • system (value 0, this is set by default for exceptions generated by the system, like out of quota and out of memory, user-defined alarms cannot have the value 0, it is reserved)
  • user (value 1, for generic user-defined alarms)
  • exception (value 2, for exceptions)
  • traceback (value 3, for tracebacks)
  • log (value 4, for generic logging)

Filtering alarms

the /alarms/ api takes optional search-filters as a query string.

As an example you can filter all the alarms of a container of a specific level:

curl https://kratos:[email protected]/api/alarms/?container=30017&level=1

The following search filters are available:

  • container
  • vassal
  • class
  • color
  • level
  • line
  • filename
  • func

Pagination of results

It is possible to paginate or limit results thanks to two additional parameters that can be mixed with search-filters:

  • with_total
  • range

using with_total the api will return the list of alarms and the total number of alarms matching the query string (if present). Note that using this parameter the api will return a dictionary instead of a list.

using range it is possible to limit results. Accepted values are:

  • single numbers (e.g. range=10 to get last ten alarms)
  • two numbers separated by a '-' (e.g. range=10-20 to get alarms between the two values). If the first value is greater than the second one, you'll get the same alarms but in reversed order.
curl https://kratos:[email protected]/api/alarms/?range=20-10&container=30017&with_total

Generating alarms

You can generate your alarms (to be stored in the api database) via the /alarms/raise/ api (aliased as /alarms/trigger/). is the uid of the container, while the body of the request is the raw body of the alarm:

curl -X POST -d "it's a trap" https://kratos:[email protected]/api/alarms/raise/30017

will create an alarm with the message "it's a trap" for the container 30017

You can pass additional fields value for the alarm as a query string, so for defining the color red and the class 'starwars' you will use:

curl -X POST -d "it's a trap" https://kratos:[email protected]/api/alarms/raise/30017?color=ff0000&class=starwars

Til now we have used the customer credentials to generate alarms, but you may want to allow your user to define them or you can simply do not want to store your credentials in your app. For this reason a second authentication mechanism is available for raising alarms based on authentication token.

The first step is generating an authentication key/token for the container using the /alarm_key/ api:

curl https://kratos:[email protected]/api/alarm_key/30017

this will generate an authentication token (it is a uuid) for the container 30017

Now you can raise/trigger alarms using this token:

curl -X POST -d "it's a trap" https://foobar.com/api/alarms/raise/30017?color=ff0000&class=starwars&key=c5450a13-0f18-432f-9a37-74871d57cb20

Deleting alarms

Alarms are automatically deleted when you fill all of the available slots. By the way you can delete alarms manually using the DELETE method on the /alarms/ api:

curl -X DELETE https://kratos:[email protected]/api/alarms/1717

will delete the alarm with id 1717