Results API

Reference documentation

The /results API endpoint

The /results API endpoint provides HTTP GET and HTTP POST access to current check result data.

/results (GET)

The /results API endpoint provides HTTP GET access to fetch current check result data.

EXAMPLES

The following example demonstrates a /results API query which returns a JSON Array of JSON Hashes containing check results.

$ curl -s http://localhost:4567/results | jq .
[
  {
    "check": {
      "status": 1,
      "output": "CheckHttp WARNING: 301\n",
      "command": "check-http.rb -u :::website|http://sensuapp.org:::",
      "subscribers": [
        "production"
      ],
      "interval": 60,
      "handler": "mail",
      "name": "sensu_website",
      "issued": 1460312322,
      "executed": 1460312322,
      "duration": 0.032,
      "history": [0, 0, 0, 0, 1, 2, 2, 0, 0, 1]
    },
    "client": "client-01"
  },
  {
    "check": {
      "status": 0,
      "output": "Keepalive sent from client 2 seconds ago",
      "executed": 1460312365,
      "issued": 1460312365,
      "name": "keepalive",
      "thresholds": {
        "critical": 180,
        "warning": 120
      },
      "history": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
    },
    "client": "client-01"
  }
]

API specification

/results (GET)
description Returns a list of current check results for all clients.
example url http://hostname:4567/results
pagination see pagination
response type Array
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
[
  {
    "client": "i-424242",
    "check": {
      "name": "chef_client_process",
      "command": "check-procs.rb -p chef-client -W 1",
      "subscribers": [
        "production"
      ],
      "interval": 60,
      "issued": 1389374667,
      "executed": 1389374667,
      "output": "WARNING Found 0 matching processes\n",
      "status": 1,
      "duration": 0.032,
      "history": [0, 0, 0, 0, 1, 2, 2, 0, 0, 1]
    }
  }
]

/results (POST)

The /results API endpoint provides HTTP POST access to submit check result data.

EXAMPLES

The following example demonstrates submitting an HTTP POST to the /results API with JSON Hash payload containing check result data, resulting in a 202 (Accepted) HTTP response code (i.e. HTTP/1.1 202 Accepted) and a JSON Hash containing an issued timestamp.

$ curl -s -i -X POST \
-H 'Content-Type: application/json' \
-d '{"source": "external_service", "name": "check_external", "output": "hello results API world", "status": 0}' \
http://localhost:4567/results

HTTP/1.1 202 Accepted
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
Content-Length: 21
Connection: keep-alive
Server: thin

{"issued":1460326288}

API specification

/results (POST)
description Accepts Sensu check result data via API.
example url http://hostname:4567/results
response type HTTP-header only (no output)
response codes
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)
example payload 
{
  "source": "docker_01",
  "name": "index_app_01",
  "output": "Indexing app is OK",
  "status": 0
}
_NOTE: See payload parameters section for description of required and optional payload parameters._
output 
HTTP/1.1 202 Accepted
  Content-Type: application/json
  Access-Control-Allow-Origin: *
  Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
  Access-Control-Allow-Credentials: true
  Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
  Content-Length: 21
  Connection: keep-alive
  Server: thin

  {"issued":1460326288}

Payload parameters

Required payload parameters for /results (POST) API are described below.

Similar to a check definition, this API endpoint allows for additional check attributes, including custom attributes. See the check definition specification for more information.

name
description The check name provided by the check definition
required true
type String
example 
"name": "sensu-website"
status
description The check execution exit status code. An exit status code of 0 (zero) indicates OK, 1 indicates WARNING, and 2 indicates CRITICAL. Exit status codes other than 0, 1, or 2 indicate an UNKNOWN or custom status.
required true
type Integer
example 
"status": 0
output
description Text to associate with the check result (e.g. human-readable message or formatted metric data)
required true
type String
example 
"output": "CheckHttp OK: 200, 78572 bytes\n"
source
description The check source, used to create a [proxy client][32] for an external resource (e.g. a network switch)
required true, unless client is specified
type String
validated /^[\w\.-]+$/
example 
"source": "switch-dc-01"
client
description The name of the Sensu client that generated the check result
required true, unless source is specified
type String
validated /^[\w\.-]+$/
example 
"client": "i-424242"

The /results/:client API endpoint

/results/:client (GET)

The /results/:client API endpoint provides HTTP GET access to check result data for a specific :client.

EXAMPLES

The following example demonstrates a /results/:client API query which returns a JSON Array of JSON Hashes containing check results for the :client named client-01.

$ curl -s http://localhost:4567/results/client-01 | jq .
[
  {
    "check": {
      "status": 1,
      "output": "CheckHttp WARNING: 301\n",
      "command": "check-http.rb -u :::website|http://sensuapp.org:::",
      "subscribers": [
        "production"
      ],
      "interval": 60,
      "handler": "mail",
      "name": "sensu_website",
      "issued": 1460312322,
      "executed": 1460312322,
      "duration": 0.032,
      "history": [0, 0, 0, 0, 1, 2, 2, 0, 0, 1]
    },
    "client": "client-01"
  },
  {
    "check": {
      "status": 0,
      "output": "Keepalive sent from client 2 seconds ago",
      "executed": 1460312365,
      "issued": 1460312365,
      "name": "keepalive",
      "thresholds": {
        "critical": 180,
        "warning": 120
      },
      "history": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
    },
    "client": "client-01"
  }
]

API specification

/results/:client (GET)
description Returns a list of current check results for a given client.
example url http://hostname:4567/results/i-424242
pagination see pagination
response type Array
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
[
  {
    "client": "i-424242",
    "check": {
      "name": "chef_client_process",
      "command": "check-procs.rb -p chef-client -W 1",
      "subscribers": [
        "production"
      ],
       "interval": 60,
      "issued": 1389374667,
      "executed": 1389374667,
      "output": "WARNING Found 0 matching processes\n",
      "status": 1,
      "duration": 0.032,
      "history": [0, 0, 0, 0, 1, 2, 2, 0, 0, 1]
    }
  }
]

The /results/:client/:check API endpoints

The /results/:client/:check API endpoint provides HTTP GET and HTTP DELETE access to check result data for a named :client and :check.

/results/:client/:check (GET)

EXAMPLES

The following example demonstrates a /results/:client/:check API query which returns a JSON Hash containing the most recent check result for the :client named client-01 and the :check named :.

$ curl -s http://localhost:4567/results/client-01/sensu_website | jq .
{
  "check": {
    "status": 1,
    "output": "CheckHttp WARNING: 301\n",
    "command": "check-http.rb -u :::website|http://sensuapp.org:::",
    "subscribers": [
      "production"
    ],
    "interval": 60,
    "handler": "mail",
    "name": "sensu_website",
    "issued": 1460312622,
    "executed": 1460312622,
    "duration": 0.032,
    "history": [0, 0, 0, 0, 1, 2, 2, 0, 0, 1]
  },
  "client": "client-01"
}

API specification

/results/:client/:check (GET)
description Returns a check result for a given client & check name.
example url http://hostname:4567/results/i-424242/chef_client_process
response type Hash
response codes
  • Success: 200 (OK)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)
output 
{
    "client": "i-424242",
    "check": {
      "name": "chef_client_process",
      "command": "check-procs.rb -p chef-client -W 1",
      "subscribers": [
        "production"
      ],
      "interval": 60,
      "issued": 1389374667,
      "executed": 1389374667,
      "output": "WARNING Found 0 matching processes\n",
      "status": 1,
      "duration": 0.032,
      "history": [0, 0, 0, 0, 1, 2, 2, 0, 0, 1]
    }
  }

/results/:client/:check (DELETE)

EXAMPLES

The following example demonstrates a /results/:client/:check request to delete check result data for a :client named client-01 and a :check named sensu_website, resulting in a 204 (No Content) HTTP response code (i.e. HTTP/1.1 204 No Content), indicating that the result was successful, but that no content is provided as output.

curl -s -i -X DELETE http://localhost:4567/results/client-01/sensu_website
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
Connection: close
Server: thin

API specification

/results/:client/:check (DELETE)
description Delete a check result for a given client & check name.
example url http://hostname:4567/results/i-424242/chef_client_process
response type HTTP-header only (No Content)
response codes
  • Success: 204 (No Content)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)
output 
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
Connection: close
Server: thin