Status SDK

SDK for status check & reporting

How to use

ESM:

import { status } from 'status-sdk';

CJS:

const { status } = require('status-sdk');

Upon calling the enable function, the Status SDK will initiate the process monitor and automatically transmit crash/unhandled events to your Status API, as specified in the function parameters.

Setup for automatic unhandled promise/exception report

status.enable({
  // Site ID to be reported
  siteId: '<your_site_id>',
  // API key of the Status API
  apiKey: '<your_api_key>',
  // API URL for serving the status report
  apiUrl: 'https://your_domain/your/api/context/path'
});

The Status SDK does not assist in managing uncaught exceptions; when they occur, the application will shut down. If any unhandled promises are present, a warning will be generated, such as PromiseRejectionHandledWarning: Promise rejection was handled asynchronously, since the unhandled promises are intercepted by the Status SDK.

Codes to indicate the status being reported

| Group | Status flag | | ----------- | ----------------------------------- | | Good | UP | | Information | INFO, DEBUG | | Unknown | UNKNOWN | | Warning | TIMEOUT, WARNING, MAINTENANCE | | Danger | OUTAGE, CRASH, ERROR |

Active report

The active report function executes an HTTP request to your Status API and returns an HTTP code. In its implementation, there is no promise rejection, making the try ... catch block unnecessary. This is done to prevent the generation of infinite calls when the app fails due to unhandled promises.

import { status, FLAGS } from 'status-sdk';
const { code, data } = await status.report(FLAGS.ERROR, 'This is an error.');

console.log(code, data);

Events

Status SDK inherits EventEmitter class in order to emit or listen on the events defined blow:

| Description | Status code | | --------------------------------------- | ----------- | | Automatic report enabled | ENABLED | | Automatic report disabled | DISABLED | | Fires when it is sending warning report | WARNING | | Fires when the report is sent | REPORTED | | The final signal when the app crashes | EXIT |

And this is how it can be used:

import { status, EVENTS } from 'status-sdk';

status.on(ENABLED, () => {
  // The status SDK is enabled for collecting data for report
});
status.on(DISABLED, () => {
  // The status SDK is disabled
});

// status.enable({ ... });

Status API standard

The Status API serves the purpose of collecting status data, processing it, and generating reports. It must be compatible with the data sent by the Status SDK.

1. POST method is required with apikey header to verify the identity of the HTTP request
2. id as the path parameter to determine an environment/application
3. body data payload format

{
  "status": "enum", // See the note blow
  "logs": "string",
  "cpu": {
    "user": "number",
    "system": "number"
  },
  "memory": {
    "rss": "number",
    "heapTotal": "number",
    "heapUsed": "number",
    "external": "number",
    "arrayBuffers": "number"
  },
}

• For status string, please refer to the Codes to indicate the status being reported section

Full example of setup

import { status } from 'status-sdk';

status.enable({
  // Site ID to be reported
  siteId: '000001',
  // API key of the Status API
  apiKey: 'apikey',
  // API URL for serving the status report
  apiUrl: 'https://mihui.net/api/status/report',
  // Set to true to disable the automatic error/crash report, by default it is set to false
  manualOnly: false,
  // Custom headers to the Status API, `apikey` is preserved above
  headers: { key: 'value' }
});

Other useful methods

// Disable Status SDK
disable(userProcess: NodeJS.Process|undefined): StatusInterface;

// Get request URL
getRequestUrl() : string;

// Get API URL
getApiUrl(): string;

// Set API URL
setApiUrl(apiUrl: string): void;

// Add HTTP header
addHeader(key: string, value: string): void;

// Get HTTP headers
getHeaders(): http.OutgoingHttpHeaders;