Events API
The /events
API endpoint
/events
(GET)
The /events
API endpoint provides HTTP GET access to event data.
EXAMPLE
The following example demonstrates a request to the /events
API, resulting in
a JSON Array containing event definitions.
curl -H "Authorization: Bearer $SENSU_TOKEN" \
http://127.0.0.1:8080/api/core/v2/namespaces/default/events
HTTP/1.1 200 OK
[
{
"timestamp": 1542667666,
"entity": {
"entity_class": "agent",
"system": {
"hostname": "webserver01",
"...": "...",
"arch": "amd64"
},
"subscriptions": [
"testing",
"entity:webserver01"
],
"metadata": {
"name": "check-nginx",
"namespace": "default",
"labels": null,
"annotations": null
}
},
"check": {
"check_hooks": null,
"duration": 2.033888684,
"command": "http_check.sh http://localhost:80",
"handlers": [
"slack"
],
"high_flap_threshold": 0,
"interval": 20,
"low_flap_threshold": 0,
"publish": true,
"runtime_assets": [],
"subscriptions": [
"testing"
],
"proxy_entity_name": "",
"check_hooks": null,
"stdin": false,
"ttl": 0,
"timeout": 0,
"duration": 0.010849143,
"output": "",
"state": "failing",
"status": 1,
"total_state_change": 0,
"last_ok": 0,
"occurrences": 1,
"occurrences_watermark": 1,
"output_metric_format": "",
"output_metric_handlers": [],
"env_vars": null,
"metadata": {
"name": "check-nginx",
"namespace": "default",
"labels": null,
"annotations": null
}
}
}
]
API Specification
/events (GET) | |
---|---|
description | Returns the list of events. |
example url | http://hostname:8080/api/core/v2/namespaces/default/events |
pagination | This endpoint supports pagination using the limit and continue query parameters. See the API overview for details. |
response type | Array |
response codes |
|
output |
|
/events
(POST)
The /events
API endpoint provides HTTP POST access to create an event and send it to the Sensu pipeline.
EXAMPLE
In the following example, an HTTP POST request is submitted to the /events
API to create an event.
The request includes information about the check and entity represented by the event and returns a successful HTTP 200 OK response and the event definition.
curl -X POST \
-H "Authorization: Bearer $SENSU_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"entity": {
"entity_class": "proxy",
"metadata": {
"name": "server1",
"namespace": "default"
}
},
"check": {
"output": "Server error",
"state": "failing",
"status": 2,
"handlers": ["slack"],
"interval": 60,
"metadata": {
"name": "server-health"
}
}
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/events
HTTP/1.1 200 OK
{"timestamp":1552582569,"entity":{"entity_class":"proxy","system":{"network":{"interfaces":null}},"subscriptions":null,"last_seen":0,"deregister":false,"deregistration":{},"metadata":{"name":"server1","namespace":"default"}},"check":{"handlers":["slack"],"high_flap_threshold":0,"interval":60,"low_flap_threshold":0,"publish":false,"runtime_assets":null,"subscriptions":[],"proxy_entity_name":"","check_hooks":null,"stdin":false,"subdue":null,"ttl":0,"timeout":0,"round_robin":false,"executed":0,"history":null,"issued":0,"output":"Server error","state":"failing","status":2,"total_state_change":0,"last_ok":0,"occurrences":0,"occurrences_watermark":0,"output_metric_format":"","output_metric_handlers":null,"env_vars":null,"metadata":{"name":"server-health"}},"metadata":{}}
/events
(PUT)
The /events
API endpoint provides HTTP PUT access to create an event and send it to the Sensu pipeline.
EXAMPLE
In the following example, an HTTP PUT request is submitted to the /events
API to create an event.
The request includes information about the check and entity represented by the event and returns a successful HTTP 200 OK response and the event definition.
curl -X PUT \
-H "Authorization: Bearer $SENSU_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"entity": {
"entity_class": "proxy",
"metadata": {
"name": "server1",
"namespace": "default"
}
},
"check": {
"output": "Server error",
"state": "failing",
"status": 2,
"handlers": ["slack"],
"interval": 60,
"metadata": {
"name": "server-health"
}
}
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/events
HTTP/1.1 200 OK
{"timestamp":1552582569,"entity":{"entity_class":"proxy","system":{"network":{"interfaces":null}},"subscriptions":null,"last_seen":0,"deregister":false,"deregistration":{},"metadata":{"name":"server1","namespace":"default"}},"check":{"handlers":["slack"],"high_flap_threshold":0,"interval":60,"low_flap_threshold":0,"publish":false,"runtime_assets":null,"subscriptions":[],"proxy_entity_name":"","check_hooks":null,"stdin":false,"subdue":null,"ttl":0,"timeout":0,"round_robin":false,"executed":0,"history":null,"issued":0,"output":"Server error","state":"failing","status":2,"total_state_change":0,"last_ok":0,"occurrences":0,"occurrences_watermark":0,"output_metric_format":"","output_metric_handlers":null,"env_vars":null,"metadata":{"name":"server-health"}},"metadata":{}}
API Specification
/events (POST) | |
---|---|
description | Create a Sensu event for a new entity and check combination. To create an event for an existing entity and check combination or to update an existing event, use the /events/:entity/:check PUT endpoint. |
example URL | http://hostname:8080/api/core/v2/namespaces/default/events |
payload |
|
payload parameters | See the payload parameters section for the /events/:entity/:check PUT endpoint. |
response codes |
|
The /events/:entity
API endpoint
/events/:entity
(GET)
The /events/:entity
API endpoint provides HTTP GET access to event data specific to an :entity
, by entity name
.
EXAMPLE
In the following example, querying the /events/:entity
API returns a list of Sensu events for the sensu-go-sandbox
entity and a successful HTTP 200 OK response.
curl -H "Authorization: Bearer $SENSU_TOKEN" \
http://127.0.0.1:8080/api/core/v2/namespaces/default/events/sensu-go-sandbox
HTTP/1.1 200 OK
[
{
"timestamp": 1543871497,
"entity": {
"entity_class": "agent",
"system": {
"hostname": "webserver01",
"...": "...",
"arch": "amd64"
},
"subscriptions": [
"linux",
"entity:sensu-go-sandbox"
],
"last_seen": 1543858763,
"metadata": {
"name": "sensu-go-sandbox",
"namespace": "default"
}
},
"check": {
"command": "check-cpu.sh -w 75 -c 90",
"duration": 1.054253257,
"executed": 1543871496,
"history": [
{
"status": 0,
"executed": 1543870296
}
],
"issued": 1543871496,
"output": "CPU OK - Usage:.50\n",
"state": "passing",
"status": 0,
"total_state_change": 0,
"last_ok": 1543871497,
"occurrences": 1,
"metadata": {
"name": "check-cpu",
"namespace": "default"
}
},
"metadata": {
"namespace": "default"
}
},
{
"timestamp": 1543871524,
"entity": {
"entity_class": "agent",
"system": {
"hostname": "webserver01",
"...": "...",
"arch": "amd64"
},
"subscriptions": [
"linux",
"entity:sensu-go-sandbox"
],
"last_seen": 1543871523,
"metadata": {
"name": "sensu-go-sandbox",
"namespace": "default"
}
},
"check": {
"handlers": [
"keepalive"
],
"executed": 1543871524,
"history": [
{
"status": 0,
"executed": 1543871124
}
],
"issued": 1543871524,
"output": "",
"state": "passing",
"status": 0,
"total_state_change": 0,
"last_ok": 1543871524,
"occurrences": 1,
"metadata": {
"name": "keepalive",
"namespace": "default"
}
},
"metadata": {}
}
]
API Specification
/events/:entity (GET) | |
---|---|
description | Returns a list of events for the specified entity. |
example url | http://hostname:8080/api/core/v2/namespaces/default/events/sensu-go-sandbox |
pagination | This endpoint supports pagination using the limit and continue query parameters. See the API overview for details. |
response type | Array |
response codes |
|
output |
|
The /events/:entity/:check
API endpoint
/events/:entity/:check
(GET)
API Specification
/events/:entity/:check (GET) | |
---|---|
description | Returns an event for a given entity and check. |
example url | http://hostname:8080/api/core/v2/namespaces/default/events/sensu-go-sandbox/check-cpu |
response type | Map |
response codes |
|
output |
|
/events/:entity/:check
(POST)
The /events/:entity/:check
API endpoint provides HTTP POST access to create or update an event and send it to the Sensu pipeline.
EXAMPLE
In the following example, an HTTP POST request is submitted to the /events/:entity/:check
API to create an event for the server1
entity and the server-health
check and process it using the slack
event handler.
The event includes a status code of 1
, indicating a warning, and an output message of “Server error”.
curl -X POST \
-H "Authorization: Bearer $SENSU_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"entity": {
"entity_class": "proxy",
"metadata": {
"name": "server1",
}
},
"check": {
"output": "Server error",
"status": 1,
"handlers": ["slack"],
"interval": 60,
"metadata": {
"name": "server-health"
}
}
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/events/server1/server-health
The request returns a 200 (OK) HTTP response code and the resulting event definition. Note that a namespace is not required to create the event. The event will use the namspace in the URL by default.
HTTP/1.1 200 OK
{"timestamp":1552582569,"entity":{"entity_class":"proxy","system":{"network":{"interfaces":null}},"subscriptions":null,"last_seen":0,"deregister":false,"deregistration":{},"metadata":{"name":"server1","namespace":"default"}},"check":{"handlers":["slack"],"high_flap_threshold":0,"interval":60,"low_flap_threshold":0,"publish":false,"runtime_assets":null,"subscriptions":[],"proxy_entity_name":"","check_hooks":null,"stdin":false,"subdue":null,"ttl":0,"timeout":0,"round_robin":false,"executed":0,"history":null,"issued":0,"output":"Server error","status":1,"total_state_change":0,"last_ok":0,"occurrences":0,"occurrences_watermark":0,"output_metric_format":"","output_metric_handlers":null,"env_vars":null,"metadata":{"name":"server-health"}},"metadata":{}}
You can use sensuctl or the Sensu dashboard to see the event.
sensuctl event list
You should see the event with the status and output specified in the request.
Entity Check Output Status Silenced Timestamp
────────────── ───────────── ─────────────────────────────────── ──────── ────────── ───────────────────────────────
server1 server-health Server error 1 false 2019-03-14 16:56:09 +0000 UTC
/events/:entity/:check
(PUT)
The /events/:entity/:check
API endpoint provides HTTP PUT access to create or update an event and send it to the Sensu pipeline.
EXAMPLE
In the following example, an HTTP PUT request is submitted to the /events/:entity/:check
API to create an event for the server1
entity and the server-health
check and process it using the slack
event handler.
The event includes a status code of 1
, indicating a warning, and an output message of “Server error”.
curl -X PUT \
-H "Authorization: Bearer $SENSU_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"entity": {
"entity_class": "proxy",
"metadata": {
"name": "server1",
"namespace": "default"
}
},
"check": {
"output": "Server error",
"status": 1,
"handlers": ["slack"],
"interval": 60,
"metadata": {
"name": "server-health"
}
}
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/events/server1/server-health
The request returns a 200 (OK) HTTP response code and the resulting event definition. Note that a namespace is not required to create the event. The event will use the namspace in the URL by default.
HTTP/1.1 200 OK
{"timestamp":1552582569,"entity":{"entity_class":"proxy","system":{"network":{"interfaces":null}},"subscriptions":null,"last_seen":0,"deregister":false,"deregistration":{},"metadata":{"name":"server1","namespace":"default"}},"check":{"handlers":["slack"],"high_flap_threshold":0,"interval":60,"low_flap_threshold":0,"publish":false,"runtime_assets":null,"subscriptions":[],"proxy_entity_name":"","check_hooks":null,"stdin":false,"subdue":null,"ttl":0,"timeout":0,"round_robin":false,"executed":0,"history":null,"issued":0,"output":"Server error","status":1,"total_state_change":0,"last_ok":0,"occurrences":0,"occurrences_watermark":0,"output_metric_format":"","output_metric_handlers":null,"env_vars":null,"metadata":{"name":"server-health"}},"metadata":{}}
You can use sensuctl or the Sensu dashboard to see the event.
sensuctl event list
You should see the event with the status and output specified in the request.
Entity Check Output Status Silenced Timestamp
────────────── ───────────── ─────────────────────────────────── ──────── ────────── ───────────────────────────────
server1 server-health Server error 1 false 2019-03-14 16:56:09 +0000 UTC
API Specification
/events/:entity/:check (PUT) | |
---|---|
description | Creates an event for a given entity and check. |
example url | http://hostname:8080/api/core/v2/namespaces/default/events/server1/server-health |
payload |
|
payload parameters | See the payload parameters section below. |
response codes |
|
Payload parameters
The /events/:entity/:check
PUT endpoint requires a request payload containing an entity
scope and a check
scope.
The entity
scope contains information about the component of your infrastructure represented by the event.
At a minimum, Sensu requires the entity
scope to contain the entity_class
(agent
or proxy
) and the entity name
and namespace
within a metadata
scope.
For more information about entity attributes, see the entity specification.
The check
scope contains information about the event status and how the event was created.
At a minimum, Sensu requires the check
scope to contain a name
within a metadata
scope and either an interval
or cron
attribute.
For more information about check attributes, see the check specification.
Example request with minimum required event attributes
curl -X PUT \
-H "Authorization: Bearer $SENSU_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"entity": {
"entity_class": "proxy",
"metadata": {
"name": "server1",
"namespace": "default"
}
},
"check": {
"interval": 60,
"metadata": {
"name": "server-health"
}
}
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/events/server1/server-health
The minimum required attributes shown above let you create an event using the /events/:entity/:check
PUT endpoint, however the request can include any attributes defined in the event specification.
To create useful, actionable events, we recommend adding check attributes such as the event status
(0
for OK, 1
for warning, 2
for critical), an output
message, and one or more event handlers
.
For more information about these attributes and their available values, see the event specification.
Example request with minimum recommended event attributes
curl -X PUT \
-H "Authorization: Bearer $SENSU_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"entity": {
"entity_class": "proxy",
"metadata": {
"name": "server1",
"namespace": "default"
}
},
"check": {
"output": "Server error",
"status": 1,
"handlers": ["slack"],
"interval": 60,
"metadata": {
"name": "server-health"
}
}
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/events/server1/server-health
Creating metric events
In addition to the entity
and check
scopes, Sensu events can include a metrics
scope containing metrics in Sensu metric format.
See the events reference and for more information about Sensu metric format.
Example request including metrics
curl -X PUT \
-H "Authorization: Bearer $SENSU_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"entity": {
"entity_class": "proxy",
"metadata": {
"name": "server1",
"namespace": "default"
}
},
"check": {
"status": 0,
"output_metric_handlers": ["influxdb"],
"interval": 60,
"metadata": {
"name": "server-metrics"
}
},
"metrics": {
"handlers": [
"influxdb"
],
"points": [
{
"name": "server1.server-metrics.time_total",
"tags": [],
"timestamp": 1552506033,
"value": 0.005
},
{
"name": "server1.server-metrics.time_namelookup",
"tags": [],
"timestamp": 1552506033,
"value": 0.004
}
]
}
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/events/server1/server-metrics
/events/:entity/:check
(DELETE)
EXAMPLE
The following example shows a request to delete the event produced by the sensu-go-sandbox
entity and check-cpu
check, resulting in a successful HTTP 204 No Content response.
curl -X DELETE \
-H "Authorization: Bearer $SENSU_TOKEN" \
http://127.0.0.1:8080/api/core/v2/namespaces/default/events/sensu-go-sandbox/check-cpu
HTTP/1.1 204 No Content
API Specification
/events/:entity/:check (DELETE) | |
---|---|
description | Deletes the event created by the specified entity using the specified check |
example url | http://hostname:8080/api/core/v2/namespaces/default/events/sensu-go-sandbox/check-cpu |
response codes |
|