Health reference

Use Sensu’s /health API to make sure your backend is up and running and check the health of your etcd cluster members and PostgreSQL datastore resources.

A request to the /health API endpoint retrieves a JSON map with health data for your Sensu instance. Here’s an example request to the health endpoint:

curl -X GET \
http://127.0.0.1:8080/health

Healthy cluster example

In this example, all cluster members are healthy.

{
  "Alarms": null,
  "ClusterHealth": [
    {
      "MemberID": 9861478486968594000,
      "MemberIDHex": "88db026f7feb72b4",
      "Name": "backend01",
      "Err": "",
      "Healthy": true
    },
    {
      "MemberID": 16828500076473182000,
      "MemberIDHex": "e98ad7a888d16bd6",
      "Name": "backend02",
      "Err": "",
      "Healthy": true
    },
    {
      "MemberID": 848052855499371400,
      "MemberIDHex": "bc4e39432cbb36d",
      "Name": "backend03",
      "Err": "",
      "Healthy": true
    }
  ],
  "Header": {
    "cluster_id": 17701109828877156000,
    "member_id": 16828500076473182000,
    "raft_term": 42
  }
},
  "PostgresHealth": [
    {
      "Name": "my-first-postgres",
      "Active": true,
      "Healthy": true
    },
    {
      "Name": "my-other-postgres",
      "Active": false,
      "Healthy": false
    }
  ]
}

Unhealthy cluster member example

In this example, one cluster member is unhealthy: it cannot communicate with the other cluster members.

{
  "Alarms": null,
  "ClusterHealth": [
    {
      "MemberID": 9861478486968594000,
      "MemberIDHex": "88db026f7feb72b4",
      "Name": "backend01",
      "Err": "context deadline exceeded",
      "Healthy": false
    },
    {
      "MemberID": 16828500076473182000,
      "MemberIDHex": "e98ad7a888d16bd6",
      "Name": "backend02",
      "Err": "",
      "Healthy": true
    },
    {
      "MemberID": 848052855499371400,
      "MemberIDHex": "bc4e39432cbb36d",
      "Name": "backend03",
      "Err": "",
      "Healthy": true
    }
  ],
  "Header": {
    "cluster_id": 17701109828877156000,
    "member_id": 16828500076473182000,
    "raft_term": 42
  }
},
  "PostgresHealth": [
    {
      "Name": "my-first-postgres",
      "Active": true,
      "Healthy": true
    },
    {
      "Name": "my-other-postgres",
      "Active": false,
      "Healthy": false
    }
  ]
}

NOTE: The HTTP response codes for the health endpoint indicate whether your request reached Sensu rather than the health of your Sensu instance. In this example, even though the cluster is unhealthy, the request itself reached Sensu, so the response code is 200 OK. To determine the health of your Sensu instance, you must process the JSON response body. The health specification describes each attribute in the response body.

Health specification

Top-level attributes

Alarms
description Top-level attribute that lists all active etcd alarms.
required true
type String
example 
"Alarms": null
ClusterHealth
description Top-level attribute that includes health status information for every etcd cluster member.
required true
type Map of key-value pairs
example 
"ClusterHealth": [
    {
      "MemberID": 2882886652148554927,
      "MemberIDHex": "8923110df66458af",
      "Name": "default",
      "Err": "",
      "Healthy": true
    }
  ]
Header
description Top-level map that includes the response header for the entire cluster response.
required true
type Map of key-value pairs
example 
"Header": {
    "cluster_id": 4255616344056076734,
    "member_id": 2882886652148554927,
    "raft_term": 26
  }
PostgresHealth
description Top-level map that includes health information for PostgreSQL resources. If your Sensu instance is not configured to use a PostgreSQL datastore, the health payload will not include PostgresHealth.
type Map of key-value pairs
example 
"PostgresHealth": [
    {
      "Name": "postgres-test",
      "Active": false,
      "Healthy": false
    },
    {
      "Name": "postgres",
      "Active": true,
      "Healthy": true
    }
  ]

ClusterHealth attributes

Err
description Any errors Sensu encountered while checking the etcd cluster member’s health.
required true
type String
example 
"Err": ""
Healthy
description true if the etcd cluster member is connected. Otherwise, false.
required true
type Boolean
default false
example 
"Healthy": true
MemberID
description The etcd cluster member’s ID.
required true
type Integer
example 
"MemberID": 2882886652148554927
MemberIDHex
description The hexadecimal representation of the etcd cluster member’s ID.
required true
type String
example 
"MemberIDHex": "8923110df66458af"
Name
description The etcd cluster member’s name.
required true
type String
example 
"Name": "default"

Header attributes

cluster_id
description The etcd cluster ID.
required true
type Integer
example 
"cluster_id": 4255616344056076734
member_id
description The etcd cluster member’s ID.
required true
type Integer
example 
"member_id": 2882886652148554927
raft_term
description The etcd cluster member’s raft term.
required true
type Integer
example 
"raft_term": 26

PostgresHealth attributes

Active
description true if the datastore is configured to use the PostgreSQL configuration. Otherwise, false.
required true
type Boolean
default false
example 
"Active": true
Healthy
description true if the PostgreSQL datastore is connected and can query the events table. Otherwise, false.
required true
type Boolean
default false
example 
"Healthy": true
Name
description The PostgreSQL configuration resource. Sensu retrieves the Name from datastore metadata.
required true
type String
example 
"Name": "postgres"