Enterprise API

Reference documentation

What is the Sensu Enterprise API?

Every instance of Sensu Enterprise provides the Sensu Enterprise API, built upon the Sensu Core API.

The Sensu Enterprise API has the functionality of the Core API with the addition of several endpoints to provide access to data for generating reports, visualizing internal metrics, and more. The Enterprise API also supports native SSL, for end-to-end SSL, eliminating the need for a proxy to terminate SSL.

Enterprise API Configuration

Example(s)

The following is an example API definition at /etc/sensu/conf.d/api.json.

{
  "api": {
    "host": "57.43.53.22",
    "bind": "0.0.0.0",
    "port": 4567,
    "ssl": {
      "port": 4568,
      "keystore_file": "/etc/sensu/api.keystore",
      "keystore_password": "secret"
    }
  }
}

API specification

api attributes

The following attributes are configured within the {"api": {} } configuration scope.

host
description The hostname or IP address that is used when querying the API. This attribute does not configure the address that the API binds to (that’s bind). This attribute is used by Sensu tooling to know how to query the Sensu API.
required false
type String
default 127.0.0.1
example 
"host": "8.8.8.8"
bind
description The address that the API will bind to (listen on).
required false
type String
default 0.0.0.0
example 
"bind": "127.0.0.1"
port
description The API HTTP port.
required false
type Integer
default 4567
example 
"port": 4242
ssl
description A set of attributes that configure SSL encryption for the API. The API SSL listener will be enabled if this attribute is configured.
required false
type Hash
example 
"ssl": {}

ssl attributes

The following attributes are configured within the {"api": { "ssl": {} } } configuration scope.

EXAMPLE
{
  "api": {
    "host": "57.43.53.22",
    "...": "...",
    "ssl": {
      "port": 4568,
      "keystore_file": "/etc/sensu/api.keystore",
      "keystore_password": "secret"
    }
  }
}
ATTRIBUTES
port
description The API HTTPS (SSL) port.
required true
type Integer
example 
"port": 4458
keystore_file
description The file path for the SSL certificate keystore. The documentation to create self-signed SSL certificates and a keystore can be found here.
required true
type String
example 
"keystore_file": "/etc/sensu/api.keystore"
keystore_password
description The SSL certificate keystore password.
required true
type String
example 
"keystore_password": "secret"

Create an SSL keystore

The following instructions will generate an OpenSSL certificate authority, self-signed certificates, and a password protected keystore for the Sensu Enterprise API. Alternatively, you may create a keystore with third-party issued SSL certificates.

Install OpenSSL

OpenSSL is required on the machine that will generate the SSL certificates. Install OpenSSL on your platform:

Ubuntu/Debian

sudo apt-get update
sudo apt-get install openssl
openssl version

CentOS/RHEL

sudo yum install openssl
openssl version

Generate SSL certificates and keystore

The generate an OpenSSL certificate authority, self-signed certificates, and a password protected keystore for the Sensu Enterprise API, run the following commands, providing information when prompted:

Create a password protected private key.

openssl genrsa -des3 -out api.key 2048

Remove the password from the private key.

cp api.key api.orig.key
openssl rsa -in api.orig.key -out api.key

Create a self-signed certificate.

openssl req -new -x509 -key api.key -out apix509.crt

Combine the self-signed certificate and private key and export it in the pkcs12 format.

openssl pkcs12 -inkey api.key -in apix509.crt -export -out api.pkcs12

Create the SSL keystore, importing api.pkcs12.

keytool -importkeystore -srckeystore api.pkcs12 -srcstoretype PKCS12 -destkeystore api.keystore

The generated keystore should be moved to an appropriate directory to limit access and allow Sensu Enterprise to load it. Move api.keystore to /etc/sensu and correct the file ownership and permissions.

sudo mv api.keystore /etc/sensu/
sudo chown sensu:sensu /etc/sensu/api.keystore
sudo chmod 600 /etc/sensu/api.keystore

Configure the Enterprise API for SSL

Once you have successfully created an SSL certificate keystore, Sensu Enterprise can be configured to provide an SSL listener for the API (HTTPS). The keystore instructions produced a password protected keystore at /etc/sensu/api.keystore, the following API definition examples loads it.

The following is an example API definition at /etc/sensu/conf.d/api.json.

{
  "api": {
    "host": "your_api_host_address",
    "bind": "0.0.0.0",
    "port": 4567,
    "ssl": {
      "port": 4568,
      "keystore_file": "/etc/sensu/api.keystore",
      "keystore_password": "your_keystore_password"
    }
  }
}

Be sure to reload Sensu Enterprise to pick up the configuration changes.

NOTE: The service command will not work on CentOS 5, the sysvinit script must be used, e.g. sudo /etc/init.d/sensu-enterprise start

sudo service sensu-enterprise reload

The /metrics API endpoints

The /metrics API endpoints provides HTTP GET access to Sensu client and monitoring event data.

/metrics/check_requests (GET)

EXAMPLES

The following example demonstrates a /metrics/check_requests API query which results in a JSON Hash containing the metric name and historical data points.

curl http://127.0.0.1:4567/metrics/check_requests

HTTP/1.1 200 OK
{
  "metric": "check_requests",
  "points": [
    [
      1547499950,
      85
    ],
    [
      1547499960,
      80
    ]
  ]
}

API specification

/metrics/check_requests (GET)
description Returns the number of Sensu check requests over the past hour at 10 second intervals in the format [timestamp, value].
example url http://hostname:4567/metrics/check_requests
response type Hash
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
{
  "metric": "check_requests",
  "points": [
    [
      1547499950,
      85
    ],
    [
      1547499960,
      80
    ]
  ]
}

/metrics/clients (GET)

EXAMPLES

The following example demonstrates a /metrics/clients API query which results in a JSON Hash containing the metric name and historical data points.

curl http://127.0.0.1:4567/metrics/clients

HTTP/1.1 200 OK
{
  "metric": "clients",
  "points": [
    [
      1547499950,
      12
    ],
    [
      1547499960,
      12
    ]
  ]
}

API specification

/metrics/clients (GET)
description Returns the number of Sensu clients over the past hour at 10 second intervals in the format [timestamp, value].
example url http://hostname:4567/metrics/clients
response type Hash
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
{
  "metric": "clients",
  "points": [
    [
      1547499950,
      12
    ],
    [
      1547499960,
      12
    ]
  ]
}

/metrics/events (GET)

EXAMPLES

The following example demonstrates a /metrics/events API query which results in a JSON Hash containing the metric name and historical data points.

curl http://127.0.0.1:4567/metrics/events

HTTP/1.1 200 OK
{
  "metric": "events",
  "points": [
    [
      1547499950,
      15
    ],
    [
      1547499960,
      13
    ]
  ]
}

API specification

/metrics/events (GET)
description Returns the number of Sensu events over the past hour at 10 second intervals in the format [timestamp, value].
example url http://hostname:4567/metrics/events
response type Hash
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
{
  "metric": "events",
  "points": [
    [
      1547499950,
      15
    ],
    [
      1547499960,
      13
    ]
  ]
}

/metrics/keepalives (GET)

EXAMPLES

The following example demonstrates a /metrics/keepalives API query which results in a JSON Hash containing the metric name and historical data points.

curl http://127.0.0.1:4567/metrics/keepalives

HTTP/1.1 200 OK
{
  "metric": "keepalives",
  "points": [
    [
      1547499950,
      64
    ],
    [
      1547499960,
      62
    ]
  ]
}

API specification

/metrics/keepalives (GET)
description Returns the number of Sensu keepalives over the past hour at 10 second intervals in the format [timestamp, value].
example url http://hostname:4567/metrics/keepalives
response type Hash
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
{
  "metric": "keepalives",
  "points": [
    [
      1547499950,
      64
    ],
    [
      1547499960,
      62
    ]
  ]
}

/metrics/results (GET)

EXAMPLES

The following example demonstrates a /metrics/results API query which results in a JSON Hash containing the metric name and historical data points.

curl http://127.0.0.1:4567/metrics/results

HTTP/1.1 200 OK
{
  "metric": "results",
  "points": [
    [
      1547499950,
      54
    ],
    [
      1547499960,
      48
    ]
  ]
}

API specification

/metrics/results (GET)
description Returns the number of Sensu check results over the past hour at 10 second intervals in the format [timestamp, value].
example url http://hostname:4567/metrics/results
response type Hash
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
{
  "metric": "results",
  "points": [
    [
      1547499950,
      54
    ],
    [
      1547499960,
      48
    ]
  ]
}