Crate health

A library to assist in reporting on the health of a system.

Usage

In order to integrate with this library, a module will need to implement the Checkable trait.

Consumers can implement the Checkable trait directly or provide a function that can perform the health check. Such a function can be either synchronous or asynchronous.

Synchronous checker

Synchronous checker functions have the form Fn() -> Result<(), Error> and can be created with check_fn().

use health::Checkable;

fn all_is_well() -> Result<(), Error> { Ok(()) }
fn everything_is_fire() -> Result<(), Error> { Err(Error {}) }

let always_ok = health::check_fn("ok", all_is_well);
let always_bad = health::check_fn("bad", everything_is_fire);

Asynchronous checker

Asynchronous checker functions have the form async Fn() -> Result<(), Error> and can be created with check_future().

use health::Checkable;

async fn all_is_well() -> Result<(), Error> { Ok(()) }
async fn everything_is_fire() -> Result<(), Error> { Err(Error {}) }

let always_ok = health::check_future("ok", all_is_well);
let always_bad = health::check_future("bad", everything_is_fire);

Periodic background health checks

Once a Checkable is created, that can be passed to a PeriodicChecker<C>, which implements the Reporter trait. The periodic checker can be configured to define the parameters for reporting a health status.

Health checks are performed periodically in the background and not inline to requests for the current health status. This ensures that information about the current health status is always available without delay, which can be particularly important for health checking endpoings on web servers (such as the oft-seen /healthz and /health endpoints).

Example

use std::time::Duration;
use health::Reporter;

async fn all_is_well() -> Result<(), Error> { Ok(()) }
let always_ok = health::check_future("ok", all_is_well);

let reporter = health::PeriodicChecker::new(always_ok, health::Config {
    check_interval: Duration::from_secs(10),
    leeway: Duration::from_secs(30),
    min_successes: 2,
    min_failures: 6,
});

// Spawn the reporter on your executor to perform
// periodic checks in the background
spawn(reporter.clone().run());

assert_eq!(health::Status::Healthy, reporter.raw_status());
assert_eq!(Some(health::Status::Healthy), reporter.status());
assert_eq!(health::Check::Pass, reporter.last_check());

Tracing

This library makes use of the tracing library to report on the health status of resources using the health target. The PeriodicChecker<C> uses the following event levels when reporting the health status after each check is complete:

• ERROR when the health status is unhealthy, and the most recent check failed.
• WARN when the health status is healthy, but the most recent check failed.
• INFO when the health status is unhealthy, but the most recent check passed.
• INFO for the report when an unhealthy resource becomes healthy.
• DEBUG when the health status is healthy, and the most recent check passed.

Features

• tokio_0_3 (default): Uses tokio v0.3 to space out periodic health checks

• tokio_0_2: Uses tokio v0.2 to space out periodic health checks

• tracing (default): Uses the tracing library to report the results of periodic health checks

Structs

Config	Configuration for a periodic health check
FnCheck	A wrapper for synchronous functions that can used as a health check data source
FutureCheck	A wrapper for asynchronous functions that can used as a health check data source
PeriodicChecker	A health reporter that periodically updates its status based on the result an underlying Checkable resource

Enums

Check	The result of a single health check run on an underlying resource
Status	The health status of resource after accounting for allowable variance in health check results

Traits

Checkable	A resource whose health can be checked
Reporter	A health status reporter

Functions

check_fn	Wraps a synchronous function as a checkable source for health checks
check_future	Wraps an asynchronous function as a checkable source for health checks