@twicpics/health-check v0.5.0

TwicPics Health Check

configurable health check server with built-in prometheus metrics for CPU and GPU

Install

In the root directory of your NodeJS project, type

yarn add @twicpics/health-check

or

npm add @twicpics/health-check

depending on the package manager you fancy the most.

Usage

const healthCheck = require( `@twicpics/health-check` );

healthCheck.createServer( options );

Routes

The health check server will expose the following routes:

All routes return plain text results.

Status codes are:

• 200 when things went properly
• 404 when a route doesn't exist
• 503 when something went wrong

/ready can issue a 503 when not ready as normal behaviour.

Out of the box, /metrics provides four metrics:

• cpu_memory: how much of the CPU memory is being used (as a ratio between 0 and 1)
• cpu_usage: how much the CPU processing power is being used (as a ratio between 0 and 1)
• gpu_memory: how much of the GPU memory is being used (as a ratio between 0 and 1)
• gpu_usage: how much the GPU processing power is being used (as a ratio between 0 and 1)

gpu_memory and gpu_usage will only be set if the Nvidia Management Library and its headers is present in the system and a compatible acceleration card is installed.

CPU metrics are for all cores combined. If the CPU features more than one core, details will be available like so:

• cpu_usage{cpu="<index>"}: how much processing power of this specific core is being used (as a ratio between 0 and 1)

Indexes are continuous and cores are in the order the OS listed them.

GPU metrics are for all compatible cards combined. If more than one card is recognized, details will be available like so:

• gpu_memory{gpu="<index>"}: how much memory of this specific GPU is being used (as a ratio between 0 and 1)
• gpu_usage{gpu="<index>"}: how much processing power of this specific GPU is being used (as a ratio between 0 and 1)

Indexes are determined by the Nvidia Management Library and may not be continuous.

Handlers

A handler is special kind of option that is a function. If provided, it is called:

• when the corresponding route is requested (health and ready)
• every period seconds when metrics are computed internally (metrics)

Handlers can be asynchronous.

health: () => void

The health handler just has to complete execution. To notify the server is unhealthy, throw an exception with a sensible error message.

Example:

healthCheck.createServer( {
    "health": () => {
        if ( somethingWrong() ) {
            throw new Error( `something is wrong` );
        }
    },
} );

metrics: () => object

This handler should return an object containing custom metrics.

Property names will be converted from camel-case to snake-case when needed.

If a property name starts with the hash symbol (#) then it is considered as a cumulative counter: only its latest, more current value will be used, no percentile shenanigans will be attempted.

Example:

healthCheck.createServer( {
    "metrics": () => ( {
        "#myCount": 16,
        "myMetric": Math.random(),
    } ),
} );

will have /metrics output something akin to

cpu_memory 0.217
cpu_usage 0.338
gpu_memory 0.02
gpu_usage 0
my_count 16
my_metric 0.502

Custom metrics must be pure numbers: strings convertible to numbers will be ignored.

If an exception is raised in the metrics handler, it is silenced and ignored.

ready: () => boolean

If the server is ready, return true. If not, return false.

Example:

const somethingSlowToStart = new SomethingSlowToStart();

healthCheck.createServer( {
    "ready": () => somethingSlowToStart.isReady(),
} );

If false is returned then /ready will issue a 503 with NOT READY as a body.

If an exception is thrown then /ready will issue a 503 with the exception message as a body,

Options