Nostradamus Prophecy Machine

    endoscope
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.0 • Public • Published

    Endoscope

    A Node.js library for creating and exposing healthchecks.

    CircleCI Test Coverage Dependency Status

    Usage

    Endoscope is used by registering probes and exposing their results via a web app framework of your choice.

    The module exports a singleton endoscopeInstance so it can be accessed anywhere in your app to register probes.

    Registering probes

    Import the endoscope instance

    import { endoscopeInstance } from "endoscope";

    Then, register a Probe. A Probe is a function that returns a Promise which resolves or rejects based on the result.

    endoscopeInstance.register(
      () =>
        new Promise((resolve, reject) => {
          someService.ping(error => {
            if (error) {
              return reject(error);
            }
     
            resolve('optional message');
          });
        })
    );

    Of course, if the probe subject returns a promise, it can be registered directly.

    endoscopeInstance.register(someservice.ping);

    Multiple registrations can be chained.

    endoscopeInstance
      .register(someservice.ping)
      .register(someOtherService.connect);

    Probe options

    Level

    Probes can be registered with various levels of importance. The default level is 0.

    endoscopeInstance.register(someservice.ping, { level: 1 });
    Timeout

    Probes can have timeouts, so that they are considered as failed if they don't resolve in a specified number of milliseconds. The default timeout is 100.

    endoscopeInstance.register(someservice.ping, { timeout: 500 });

    Usage with Fastify

    Endoscope provides a Fastify plugin for easy integration.

    import fastify from 'fastify';
    import { fastifyEndoscope } from 'endoscope';
     
    const app = fastify();
     
    app.register(fastifyEndoscope);

    The created healthcheck routes will be /healthz and /healthz/:level where level is the desired level of the healthcheck.

    Options

    The prefix, response codes and default healthcheck level can be configured during registration.

    app.register(
      fastifyEndoscope,
      {
        endoscope: {
          prefix: '/healthz',
          successCode: 200,
          errorCode: 500,
          defaultLevel: 0,
        },
      },
    );

    Usage with Express

    Since version 1.0.0, Endoscope provides a decorator function that automatically mounts the middleware in your app.

    import express from 'express';
    import { expressEndoscope } from 'endoscope';
     
    const app = express();
     
    expressEndoscope(app);

    The created healthcheck routes will be /healthz and /healthz/:level where level is the desired level of the healthcheck.

    Options

    The prefix, response codes and default healthcheck level can be configured during registration.

    expressEndoscope(app, {
      prefix: '/healthz',
      successCode: 200,
      errorCode: 500,
      defaultLevel: 0,
    });

    Usage with raw http server

    For the minimalists out there, a http request handler is provided. This is useful if your app does not expose any other endpoints and you want to minimize the number of dependencies.

    import { createServer } from 'http';
    import { httpEndoscope } from 'endoscope';
     
    createServer(httpEndoscope()).listen(8080);

    Options

    The prefix, response codes and default healthcheck level can be configured during registration.

    createServer(
      httpEndoscope({
        prefix: '/healthz',
        successCode: 200,
        errorCode: 500,
        defaultLevel: 0,
      })
    ).listen(8080);

    Healthcheck levels

    By default, all probes are created with level 0. When running the probes, by default all probes with level 0 are run.

    If you only require basic liveness check, this is all you need to use.

    For more advanced cases, where the app may be alive and should not be killed by the orchestrator but is not ready to work, a higher level check can be used, like for example the readiness check in kubernetes.

    When a level is provided to the endoscope endpoint, only probes with the level provided or lower are run.

    To use this functionality, first a probe has to be registered with a level higher than 0

    endoscopeInstance
      .register(livenessDependency.ping)
      .register(readinessDependency.ping, { level: 1 })

    Then, when /healthz or /healthz/0 is called, only livenessDependency.ping will be run. But if /healthz/1 is called, both livenessDependency.ping and readinessDependency.ping meaning that the app is alive AND ready.

    The behavior of calling /healthz without level parameter can be altered using the defaultLevel option described above.

    Install

    npm i endoscope

    DownloadsWeekly Downloads

    145

    Version

    1.3.0

    License

    MIT

    Unpacked Size

    31.9 kB

    Total Files

    33

    Last publish

    Collaborators

    • witq