SDK for status check & reporting
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.
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.
Group | Status flag |
---|---|
Good | UP |
Information |
INFO , DEBUG
|
Unknown | UNKNOWN |
Warning |
TIMEOUT , WARNING , MAINTENANCE
|
Danger |
OUTAGE , CRASH , ERROR
|
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);
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({ ... });
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.
-
POST
method is required withapikey
header to verify the identity of the HTTP request -
id
as the path parameter to determine an environment/application -
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
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' }
});
// 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;