ibm-appconfiguration-node-crash

IBM Cloud App Configuration Node Crash SDK

IBM Cloud App Configuration Crash SDK provides crash insights when integrated with your Node.js application. You can monitor and analyze the crashes and errors encountered in your Node application via the IBM Cloud App Configuration service dashboard by integrating the Crash SDK.

Note: Support for Crash Analytics has been withdrawn from the IBM Cloud App Configuration service.

Table of Contents

• Overview
• Installation
• Module Inclusion
• Initialize Client
• Reporting Node app crashes
• License

Overview

IBM Cloud App Configuration is a centralized feature management and configuration service on IBM Cloud for use with web and mobile applications, microservices, and distributed environments.

Instrument your Node application with App Configuration Crash SDK to discover problems in your application quickly.

Installation

Installation is done using the npm install command.

The Crash SDK uses ibm-appconfiguration-node-core as one of the pre-requisite.

$ npm install ibm-appconfiguration-node-core
$ npm install ibm-appconfiguration-node-crash

Include Module

To import the module

const { AppConfigurationCore } = require ('ibm-appconfiguration-node-core');

const {
  AppConfigurationCrash
} = require('ibm-appconfiguration-node-crash');

Initialize Client

Initialize the Core SDK to connect with your App Configuration service instance.

const client = AppConfigurationCore.getInstance({
  region: 'us-south',
  guid: 'xxxxx-5f61-xxxx-9f97-xxxx',
  apikey: 'abcd-1234xyz',
})

• region : Region name where the App Configuration service instance is created. Use us-south for Dallas and eu-gb for London.
• guid : Instance Id of the App Configuration service. Get it from the service credentials section of the dashboard.
• apikey : ApiKey of the App Configuration service. Get it from the service credentials section of the dashboard.

Note: The AppConfigurationCore client can be null if any of the configurations are missing or invalid.

Initialize the Crash SDK to connect with your App Configuration service instance.

const { AppConfigurationCrash } = require('ibm-appconfiguration-node-crash')
const crashInstance = AppConfigurationCrash.getInstance('App Name')

where,

• appName: Application name

Reporting Node app crashes

Crash handling by using Node process events

Unhandled errors

All kinds of errors such as Standard JavaScript errors, System errors, and User-specified errors triggered by application code and did not had an exception handling mechanism, bubbles all the way up to the event loop.

Adding a handler that is shown here will listen to such uncaught exceptions and report the errors to the App Configuration service.

/* 
In the main file (app.js or index.js), add the following
*/
   process.on('uncaughtException', function (err) {
     crashInstance.reportCrash(err)
     process.exit(1); //recommended
   })

Unhandled promises

Warnings for unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a nonzero exit code. See here.

Whenever a promise is rejected and no error handler is attached or whose rejections have not yet been handled, Crash SDK can keep track of such rejected promises.

Adding a handler that is shown here will listen to Unhandled promise rejections and report the errors to the App Configuration service.

/* 
In the main file (app.js or index.js), add the following
*/
   process.on('unhandledRejection', function (err) {
     crashInstance.reportCrash(err)
   })

Node apps with Express framework

Express comes with a built-in error handler that takes care of any errors that might be encountered in the app. This default error-handling middleware function is added at the end of the middleware function stack. See here.

All the various kinds of errors such as Standard JavaScript errors and User-specified errors that are triggered by application code and did not had an exception handling mechanism bubbles all the way up to this errorHandler middleware.

Adding a handler that is shown here will listen and report the errors to the App Configuration service.

/* 
At the end of the middleware function stack, add the below error-handling middleware function
*/
   app.use(function (err, req, res, next) {
   crashInstance.reportCrash(err)
     // you can add your custom logic, after the crash data is reported
   })

License

IBM