banshee/web-collection/web/https/api-health

Health of a web service

Reads the health endpoint of a web service, behind a token or not: the code of the answer, its time, the health and the version the service declares, and the health of each of its dependencies. Eight watches are offered, each one set on the probe.

Versions

Generic: any service whose health endpoint answers in one of the common forms read below, JSON with checks or components (the form of Spring Boot), or plain text (the form of ASP.NET Core), whatever its software.

How it works

One GET to the address of the health endpoint, the token, when set, in the header Authorization: Bearer; without a token, a public health endpoint is read as it is. The service answers in one of the common forms:

{"status": "UP", "components": {"db": {"status": "UP"}, "redis": {"status": "DOWN"}}}
{"status": "pass", "version": "2.4.1", "checks": {"database": {"status": "pass"}, "cache": {"status": "warn"}}}
Healthy

JSON (a Content-Type that holds json): the health is status, the version version, the dependencies the members of checks or, failing that, of components (the form of Spring Boot), each with its own status. A key that is not there reads missing.
Plain text (text/plain, the form of ASP.NET Core): the health is the body itself, and the version missing.
Any other type (the error page of a proxy): the health and the version read unreadable, and no dependency is returned.
The body is read whatever the code: a service that declares itself down often answers 503 with its health.
The health is said in one word: ok for ok, up, pass and healthy; down for down, fail, error, out_of_service and unhealthy; any other word as the service writes it, in lower case (degraded, warn).
The code and the time are returned whatever the body.
A service that refuses the connection, or does not answer in time, is critical: "Service down". Any other failure leaves the probe unreachable.

The token comes from protocol:http:token, a secret variable: it only goes in the header, never in a value returned. The answer is not secret, its body having carried none.

Prerequisites

The address reachable from the poller; https:// follows the TLS profile of the probe, and a certificate it refuses stops the collector as misconfigured, with its reason.
For a service behind a token, protocol:http:token set on the host or one of its folders. It goes to https:// only: a token toward http:// stops the collector as misconfigured.

Variables

Name	Label	Says	Default
`web:url`	Health endpoint address	the full address, `https://api.example/health`	—

Outputs

Name	Label	Unit	Per instance
`code`	Status code	—	no
`response-time`	Response time	ms	no
`health`	Declared health	—	no
`version`	Declared version	—	no
`dependency`	Health of the dependency	—	yes, per dependency

Watches

Name	Title	Kind	Defaults	Checked by default
`code`	Answer in error	expected value, on `code`	critical when the code is anything but 200	yes
`slow`	Slow service	above a threshold, on `response-time`	warning above 500 ms, critical above 2000 ms, for 3 runs	yes
`unhealthy`	Service not healthy	expected value, on `health`	warning when the health is anything but `ok`	yes
`down`	Service down	state to avoid, on `health`	critical on `down`	yes
`dependency-down`	Dependency down	state to avoid, on `dependency`	critical on `down`	yes
`dependency-unhealthy`	Dependency not healthy	expected value, on `dependency`	warning when the health is anything but `ok`	yes
`dependency-missing`	Dependency missing	expected instances, on `dependency`	no dependency named: it raises nothing until names are set on the probe	no
`version`	Unexpected version	expected value, on `version`	no version given: it raises nothing until a version is set on the probe	no

Limits

A body whose type says JSON but which is not JSON stops the collector as unreachable; a JSON that is not an object (a list, a bare word) stops it as misconfigured.
A dependency is read only when it is an object with its own status; the list form of some drafts ("checks": {"db": [{"status": "pass"}]}) reads missing. Nested dependencies (a dependency of a dependency) are not read.
An account in Basic is not sent: a health endpoint behind an account is read by web/https/page, with its expected text.