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.0.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"
last_ok
description The most recent time a check result indicated an ‘OK’ status for this client/check pair (generated via Ruby Time.now.to_i).
type Integer
example 1528150592
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": "i-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