Health & Info APIs

Reference documentation

How to obtain API status information

The Sensu API provides two distinct endpoints for obtaining API status information: /health and /info. The Health API provides status information about the health of the API’s connections to the Sensu data store and transport. The Info API provides a report on the status of the API, including API version, the status of the API’s connections to the Sensu data store and transport, and the number of messages and consumers in various transport queues.

The /health API endpoint

/health (GET)

The /health API provides HTTP GET access to test or verify the health of the monitoring system. The Health API is provided for monitoring Sensu — it facilitates service checks to ensure that a minimal number of Sensu servers are connected to the transport (i.e. “transport consumers”), and/or to ensure that the transport queue isn’t growing (which would indicate that the Sensu servers aren’t able to keeping up with the volume of keepalive messages and check results being produced).

NOTE: the /health API obtains its information via the /info API.

PRO TIP: the Health API messages URL parameter (e.g. /health?messages=1000) can be used to monitor the number of messages queued on the Sensu transport and then leveraged by other automation tools to trigger an “auto scaling” or similar provisioning event, to automatically add one or more Sensu servers to a Sensu installation.

EXAMPLE

In the following example, querying the /health API with the consumers URL parameter will return an HTTP response code to indicate if the expected number of consumers (i.e. Sensu servers) are processing check results. In this example we are expecting at least two (2) consumers to be running at all times (i.e. at least two Sensu servers processing check results). The 412 (Precondition Failed) HTTP response code indicates that the requested number of consumers are not registered.

curl -s -i http://127.0.0.1:4567/health?consumers=2
HTTP/1.1 412 Precondition Failed
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

NOTE: the “412 (Precondition Failed)” HTTP response code does not mean that the API itself is unavailable, but rather, it is the equivalent of a “false” response to the API query (i.e. if you want to know if there are “at least two Sensu servers processing check results?”, a 412 response code would mean “no”).

WARNING: transport “consumers” are a native concept in pubsub technology (including actual message queues like RabbitMQ). Because the Sensu transport library supports transports which are not actual message queues (e.g. Redis), some transports do not support the Health API consumers check, because they don’t support the concept of “consumers”; i.e. this means that /health?consumers=1 will always fail (returning a 412 response code) for Sensu installations using Redis as the transport, regardless of the number of Sensu servers which may be registered and processing check results.

API Specification

/health (GET)
description Returns health information on transport & Redis connections.
example url http://hostname:4567/health
parameters
  • consumers:
    • required: true
    • type: Integer
    • description: The minimum number of transport consumers to be considered healthy
    • notes: not supported for Sensu installations using Redis as the transport
  • messages:
    • required: true
    • type: Integer
    • description: The maximum amount of transport queued messages to be considered healthy
response type HTTP-header only (no content) or array
response codes
  • Success: 204 (No Content)
  • Error: 412 (Precondition Failed)
response body If applicable, the health API includes a response body containing information about the unhealthy Sensu instance. For example:
  • not connected to redis
  • not connected to transport
  • keepalive messages (x) greater than max_messages (x)
  • result messages (x) greater than max_messages (x)
  • keepalive consumers (x) less than min_consumers (x)
  • result consumers (x) less than min_consumers (x)
See the Sensu reference docs to configure Redis and the RabbitMQ transport, and visit the RabbitMQ docs for more information about messages and consumers. To detect unhealthy states and monitor RabbitMQ metrics, see the guide to monitoring Sensu.
response example 
[
  "keepalive consumers (0) less than min_consumers (1000)",
  "result consumers (0) less than min_consumers (1000)"
]
output 
HTTP/1.1 412 Precondition Failed
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

The /info API endpoint

/info (GET)

The /info API endpoint provides HTTP GET access to status information about the Sensu installation, including the API version, Sensu settings hexdigest, data store and transport connectivity, and the running Sensu servers.

PRO TIP: The Sensu settings hexdigest value is used when comparing configurations across Sensu server instances, and can be particularly useful in troubleshooting cases where there are unexpected results inside of your deployment. Note that when retrieving this value in a distributed configuration, the hexdigest value should be consistent across server instances. If the value is differing between Sensu server instances in the same environment, this indicates that the configuration between one or more servers differ from the rest of those in the environment.

EXAMPLE

$ curl -s http://127.0.0.1:4567/info | jq .
{
  "sensu": {
    "version": "1.0.0",
    "settings": {
      "hexdigest": "4041dcf9b87d3dc8523a79d944c68f99fe10f99b379989afd617201c91d75411"
    }
  },
  "redis": {
    "connected": true
  },
  "transport": {
    "name": "rabbitmq",
    "connected": true,
    "results": {
      "consumers": 0,
      "messages": 0
    },
    "keepalives": {
      "consumers": 0,
      "messages": 0
    }
  },
  "servers": [
    {
      "id": "ee193524-ef98-4477-817a-6a1c8d822c82",
      "hostname": "example",
      "address": "192.168.0.2",
      "tasks": [
        "check_request_publisher",
        "client_monitor",
        "check_result_monitor"
      ],
      "metrics": {
        "cpu": {
          "user": 45.52,
          "system": 0.95
        }
      },
      "sensu": {
        "version": "1.0.0",
        "settings": {
          "hexdigest": "4041dcf9b87d3dc8523a79d944c68f99fe10f99b379989afd617201c91d75411"
        }
      },
      "timestamp": 1488240896
    }
  ]
}

API Specification

/info (GET)
description Returns information on the Sensu installation.
example url http://hostname:4567/info
response type Hash
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
    output 
    {
  "sensu": {
    "version": "1.0.0",
    "settings": {
      "hexdigest": "4041dcf9b87d3dc8523a79d944c68f99fe10f99b379989afd617201c91d75411"
    }
  },
  "redis": {
    "connected": true
  },
  "transport": {
    "name": "rabbitmq",
    "connected": true,
    "results": {
      "consumers": 0,
      "messages": 0
    },
    "keepalives": {
      "consumers": 0,
      "messages": 0
    }
  },
  "servers": [
    {
      "id": "ee193524-ef98-4477-817a-6a1c8d822c82",
      "hostname": "example",
      "address": "192.168.0.2",
      "tasks": [
        "check_request_publisher",
        "client_monitor",
        "check_result_monitor"
      ],
      "metrics": {
        "cpu": {
          "user": 45.52,
          "system": 0.95
        }
      },
      "sensu": {
        "version": "1.0.0",
        "settings": {
          "hexdigest": "4041dcf9b87d3dc8523a79d944c68f99fe10f99b379989afd617201c91d75411"
        }
      },
      "timestamp": 1488240896
    }
  ]
}