Sensu Events

Reference documentation

What are Sensu events?

Sensu events are created to acknowledge that something potentially noteworthy has occurred, which events may then be processed by one or more event handlers to do things such as send an email, or invoke an automated action. Every Sensu event provides context, called “event data”, which contains information about the originating Sensu client and the corresponding check result.

How are Sensu events created?

A Sensu Event is created every time a check result is processed by the Sensu server, regardless of the status indicated by the check result. An Event is created by collating data from the check result, the client registry and additional context added at the time of processing.

Event actions

Sensu supports the following event actions.

  • create. Indicates a check result status change from zero to non-zero.
  • resolve. Indicates a check result status change from a non-zero to zero.
  • flapping. Indicates a rapid change in check result status.

NOTE: for more information on event actions, please see the Sensu event data specification, below.

Event data

Example event

The following is an example Sensu event. By default, event data is JSON formatted, making it language-independent and fairly human readable.

[
  {
    "id": "ef6b87d2-1f89-439f-8bea-33881436ab90",
    "action": "create",
    "timestamp": 1460172826,
    "occurrences": 2,
    "check": {
      "type": "standard",
      "total_state_change": 11,
      "history": ["0", "0", "1", "1", "2", "2"],
      "status": 2,
      "output": "No keepalive sent from client for 230 seconds (>=180)",
      "executed": 1460172826,
      "issued": 1460172826,
      "name": "keepalive",
      "thresholds": {
        "critical": 180,
        "warning": 120
      }
    },
    "client": {
      "timestamp": 1460172596,
      "version": "1.2.0",
      "socket": {
        "port": 3030,
        "bind": "127.0.0.1"
      },
      "subscriptions": [
        "production"
      ],
      "environment": "development",
      "address": "127.0.0.1",
      "name": "client-01"
    }
  }
]

Event data specification

EVENT attributes

The following attributes are available in the root scope of the event data JSON document:

id
description
Persistent unique ID for the event.
type
String
possible values
Any Ruby SecureRandom.uuid value
example
"id": "66926524-da77-41a4-92bd-365498841079"
timestamp
description
The time the event occurred in Epoch time (generated via Ruby Time.now.to_i)
type
Integer
example
"timestamp": 1460172826
action
description
The Sensu event action, providing event handlers with more information about the state change.
type
String
possible values
create, resolve, flapping
default
create
example
"action": "create"
occurrences
description
The occurrence count for the event; the number of times an event has been created for a client/check pair with the same state (check status).
type
Integer
default
1
example
"occurrences": 3
occurrences_watermark
description
The “high water mark” tracking number of occurrences at the current severity.
type
Integer
default
1
example
"occurrences_watermark": 3
check
description
The check result check attributes.
type
Hash
example
"check":{
  "name": "chef_client",
  "command": "/etc/sensu/plugins/check-chef-client.rb",
  "subscribers": [
    "production"
  ],
  "interval": 60,
  "handler": "slack",
  "issued": 1326390169,
  "output": "WARNING - Chef client process is NOT running",
  "status": 1,
  "history": [
    "0",
    "1"
  ]
}
client
description
Client attributes from the originating client, or the proxy client attributes, in the case of an event from a proxy client.
type
Hash
example
"client": {
  "name": "i-424242",
  "address": "8.8.8.8",
  "subscriptions": [
    "production",
    "webserver",
    "mysql"
  ],
  "timestamp": 1326390159
}
silenced
description
type
example
silenced_by
description
List of silence entry IDs which match this event
type
Array
example
[ "load-balancer:check_ntp" ]

check attributes

The following attributes are available in the { "check": {} } scope of the event data JSON document.

NOTE: In general, event data check attributes are fetched from Check result data during event processing, which check result will include any check definition attribute (which may include custom check definition attributes). The following specification only documents the standard set of check attributes which may be expected in an event data payload.

type
description
The check type.
default
standard
allowed values
standard, metric
type
String
example
"type": "standard"
name
description
The name as defined in the originating check definition.
type
String
required
true
example
"name": "sensu_website"
command
description
The command as defined in the originating check definition.
type
String
required
true
example
"command": "check-http.rb -u https://sensuapp.org"
subscribers
description
The subscribers as defined in the originating check definition.
type
Array
required
true
example
"subscribers": [
  "webserver"
]
interval
description
The interval, in seconds, as defined in the originating check definition.
type
Integer
required
true
example
"interval": 30
handler
description
The handler as defined in the originating check definition.
type
String
required
false
example
"handler": "slack"
handlers
description
The handlers as defined in the originating check definition.
type
Array
required
false
example
"handlers": [
  "slack"
]
issued
description
The issued timestamp (in epoch time), when Sensu issued the check request (for a subscription check or standalone check).
type
Integer
required
false
example
"issued": 1326390159
output
description
The output produced by the check, as included in the check result.
type
String
required
true
example
"output": "CheckHttp OK: 200, 78572 bytes\n"
status
description
The exit status code produced by the check, as included in the check result.
type
Integer
required
true
example
"status": 0
history
description
The history of the last 21 exit status codes produced by the check, as included in the check result.
type
Array
required
true
example
"history": [0,0,0,0,0,0,1,2,2,0,0,0,0,0,0,0,0,0,0,0,0]
source
description
The name of the proxy client to associate the event with, as included in the check result (source attribute). NOTE: the source attribute may be included in check definitions, or provided in check results published to the Sensu client input socket.
type
String
required
false
example
"source": "sensuapp.org"
origin
description
The name of the Sensu client that executed the check. NOTE: this attribute is only provided for proxy client events (i.e. events containing a source attribute.
type
String
required
false
example
"origin": "i-424242"

client attributes

The following attributes are available in the { "client": {} } scope of the event data JSON document.

NOTE: In general, event data client attributes are fetched from the Clients API during event processing, including any client definition attribute (which may include custom client definition attributes). The following specification only documents the standard set of check attributes which may be expected in an event data payload.

name
description
The name of the Sensu client (or proxy client) the event is associated with, as fetched from the Clients API.
type
String
required
true
example
"name": "1-424242"
address
description
The address of the Sensu client (or proxy client) the event is associated with, as fetched from the Clients API.
type
String
required
true
example
"address": "10.0.2.100"
subscriptions
description
The subscriptions the associated Sensu client (or proxy client) is a member of, as fetched from the Clients API.
type
Array
required
true
example
"subscriptions": [
  "webserver"
]
timestamp
description
The last keepalive timestamp (in epoch time) produced by the Sensu client (or proxy client), as fetched from the Clients API. NOTE: for proxy clients, this will usually represent the date/time when the proxy client was created, unless some external process is updating proxy client data via the Clients API (POST).
type
Integer
required
true
example
"timestamp": 1326390159

Start your FREE trial today.

Already using Sensu Core? Upgrade to Sensu Enterprise today to take advantage of its enterprise console, added-value features, built-in integrations, FREE annual training, and enterprise-class support.