Sensu 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)
desc
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)
response codes
  • Success: 204 (No Content)
  • Error: 412 (Precondition Failed)
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.

EXAMPLE

$ curl -s http://127.0.0.1:4567/info | jq .
{
  "sensu": {
    "version": "1.1.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.1.0",
        "settings": {
          "hexdigest": "4041dcf9b87d3dc8523a79d944c68f99fe10f99b379989afd617201c91d75411"
        }
      },
      "timestamp": 1488240896
    }
  ]
}

API Specification

/info (GET)
desc
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.1.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.1.0",
        "settings": {
          "hexdigest": "4041dcf9b87d3dc8523a79d944c68f99fe10f99b379989afd617201c91d75411"
        }
      },
      "timestamp": 1488240896
    }
  ]
}

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.