Status SDK

SDK for status check & reporting

How to use

---

ESM:
``javascript
import { status } from 'status-sdk';
`

CJS:
`javascript
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.

$3

`javascript
status.enable({
// Site ID to be reported
siteId: '',
// API key of the Status API
apiKey: '',
// 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.

$3

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

$3

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.

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

console.log(code, data);
`




$3

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:

`javascript
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

`json
{
"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

---

`javascript
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

---

`javascript
// 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;
``