Error Reporting: Node.js Client

Node.js idiomatic client for Error Reporting.

Error Reporting aggregates and displays errors produced in your running cloud services.

A comprehensive list of changes in each version may be found in the CHANGELOG.

Read more about the client libraries for Cloud APIs, including the older Google APIs Client Libraries, in Client Libraries Explained.

Table of contents:

Quickstart
- Before you begin
- Installing the client library
Versioning
Contributing
License

Quickstart

Before you begin

Select or create a Cloud Platform project.
Enable the Error Reporting API.
Set up authentication with a service account so you can access the API from your local workstation.

Installing the client library

npm install @google-cloud/error-reporting

This module provides custom Error Reporting support for Node.js applications. Error Reporting is a feature of Google Cloud Platform that allows in-depth monitoring and viewing of errors reported by applications running in almost any environment.

However, note that @google-cloud/logging-winston and @google-cloud/logging-bunyan automatically integrate with the Error Reporting service for Error objects logged at severity error or higher, for applications running on Google Cloud Platform.

Thus, if you are already using Winston or Bunyan in your application, and don't need custom error reporting capabilities, you do not need to use the @google-cloud/error-reporting library directly to report errors to the Error Reporting Console.

Error Reporting overview

Here's an introductory video that provides some more details:

When Errors Are Reported

The reportMode configuration option is used to specify when errors are reported to the Error Reporting Console. It can have one of three values:

'production' (default): Only report errors if the NODE_ENV environment variable is set to "production".
'always': Always report errors regardless of the value of NODE_ENV.
'never': Never report errors regardless of the value of NODE_ENV.

The reportMode configuration option replaces the deprecated ignoreEnvironmentCheck configuration option. If both the reportMode and ignoreEnvironmentCheck options are specified, the reportMode configuration option takes precedence.

The ignoreEnvironmentCheck option should not be used. However, if it is used, and the reportMode option is not specified, it can have the values:

false (default): Only report errors if the NODE_ENV environment variable is set to "production".
true: Always report errors regardless of the value of NODE_ENV.

See the Configuration section to learn how to specify configuration options.

Configuration

The following code snippet lists available configuration options. All configuration options are optional.

const {ErrorReporting} = require('@google-cloud/error-reporting');

// Using ES6 style imports via TypeScript or Babel
// import {ErrorReporting} from '@google-cloud/error-reporting';

// Instantiates a client
const errors = new ErrorReporting({
    projectId: 'my-project-id',
    keyFilename: '/path/to/keyfile.json',
    credentials: require('./path/to/keyfile.json'),
    // Specifies when errors are reported to the Error Reporting Console.
    // See the "When Errors Are Reported" section for more information.
    // Defaults to 'production'
    reportMode: 'production',
    // Determines the logging level internal to the library; levels range 0-5
    // where 0 indicates no logs should be reported and 5 indicates all logs
    // should be reported.
    // Defaults to 2 (warnings)
    logLevel: 2,
    serviceContext: {
        service: 'my-service',
        version: 'my-service-version'
    }
});

Examples

Reporting Manually

const {ErrorReporting} = require('@google-cloud/error-reporting');

// Using ES6 style imports via TypeScript or Babel
// import {ErrorReporting} from '@google-cloud/error-reporting';

// Instantiates a client
const errors = new ErrorReporting();

// Use the error message builder to customize all fields ...
const errorEvt = errors.event()
                    .setMessage('My error message')
                    .setUser('root@nexus');
errors.report(errorEvt, () => console.log('done!'));

// or just use a regular error ...
errors.report(new Error('My error message'), () => console.log('done!'));

// or one can even just use a string.
errors.report('My error message');

The stack trace associated with an error can be viewed in the error reporting console.

If the errors.report method is given an ErrorMessage object built using the errors.event method, the stack trace at the point where the error event was constructed will be used.
If the errors.report method is given an Error object, the stack trace where the error was instantiated will be used.
If the errors.report method is given a string, the stack trace at the point where errors.report is invoked will be used.

Using Express

const express = require('express');

const {ErrorReporting} = require('@google-cloud/error-reporting');

// Using ES6 style imports via TypeScript or Babel
// import {ErrorReporting} from '@google-cloud/error-reporting';

// Instantiates a client
const errors = new ErrorReporting();

const app = express();

app.get('/error', (req, res, next) => {
    res.send('Something broke!');
    next(new Error('Custom error message'));
});

app.get('/exception', () => {
    JSON.parse('{\"malformedJson\": true');
});

// Note that express error handling middleware should be attached after all
// the other routes and use() calls. See [express docs][express-error-docs].
app.use(errors.express);

app.listen(3000);

Using Hapi

const hapi = require('hapi');
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Using ES6 style imports via TypeScript or Babel
// import {ErrorReporting} from '@google-cloud/error-reporting';

// Instantiates a client
const errors = new ErrorReporting();

const server = new hapi.Server();
server.connection({ port: 3000 });
server.start();

server.route({
    method: 'GET',
    path: '/error',
    handler: (request, reply) => {
    reply('Something broke!');
    throw new Error('Custom error message');
    }
});

server.register(errors.hapi);

Using Koa

const Koa = require('koa');
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Using ES6 style imports via TypeScript or Babel
// import {ErrorReporting} from '@google-cloud/error-reporting';

// Instantiates a client
const errors = new ErrorReporting();

const app = new Koa();

app.use(errors.koa);

app.use(function *(next) {
    //This will set status and message
    this.throw('Error Message', 500);
});

// response
app.use(function *(){
    this.body = 'Hello World';
});

app.listen(3000);

Using Restify

const restify = require('restify');
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Using ES6 style imports via TypeScript or Babel
// import {ErrorReporting} from '@google-cloud/error-reporting';

// Instantiates a client
const errors = new ErrorReporting();

function respond(req, res, next) {
    next(new Error('this is a restify error'));
}

const server = restify.createServer();

server.use(errors.restify(server));
server.get('/hello/:name', respond);
server.head('/hello/:name', respond);

server.listen(3000);

Unhandled Rejections

Unhandled Rejections are not reported by default. The reporting of unhandled rejections can be enabled using the reportUnhandledRejections configuration option. See the Configuration section for more details.

If unhandled rejections are set to be reported, then, when an unhandled rejection occurs, a message is printed to standard out indicated that an unhandled rejection had occurred and is being reported, and the value causing the rejection is reported to the error-reporting console.

Catching and Reporting Application-wide Uncaught Errors

Uncaught exceptions are not reported by default. It is recommended to process uncaughtExceptions for production-deployed applications.

Note that uncaught exceptions are not reported by default because to do so would require adding a listener to the uncaughtException event. Adding such a listener without knowledge of other uncaughtException listeners can cause interference between the event handlers or prevent the process from terminating cleanly. As such, it is necessary for uncaughtExceptions to be reported manually.

const {ErrorReporting} = require('@google-cloud/error-reporting');

// Using ES6 style imports via TypeScript or Babel
// import {ErrorReporting} from '@google-cloud/error-reporting';

// Instantiates a client
const errors = new ErrorReporting();

process.on('uncaughtException', (e) => {
    // Write the error to stderr.
    console.error(e);
    // Report that same error the Cloud Error Service
    errors.report(e);
});

More information about uncaught exception handling in Node.js and what it means for your application can be found here.

Using an API Key

You may use an API key in lieu of locally-stored credentials. Please see this document on how to set up an API key if you do not already have one.

Once you have obtained an API key, you may provide it as part of the Error Reporting instance configuration:

const {ErrorReporting} = require('@google-cloud/error-reporting');

// Using ES6 style imports via TypeScript or Babel
// import {ErrorReporting} from '@google-cloud/error-reporting';

// Instantiates a client
const errors = new ErrorReporting({
    projectId: '{your project ID}',
    key: '{your api key}'
});

If a key is provided, the module will not attempt to authenticate using the methods associated with locally-stored credentials. We recommend using a file, environment variable, or another mechanism to store the API key rather than hard-coding it into your application's source.

Note: The Error Reporting instance will check if the provided API key is invalid shortly after it is instantiated. If the key is invalid, an error-level message will be logged to stdout.

Long Stack Traces

The longjohn module can be used with this library to enable long-stack-traces and updates an Error object's stack trace, by adding special line, to indicate an async jump. In longjohn version 0.2.12, for example, a single line of dashes is included in a stack trace, by default, to indicate an async jump.

Before reporting an Error object using the report method of the @google-cloud/error-reporting module, the stack trace needs to modified to remove this special line added by longjohn. Since the longjohn module can be configured to have a custom line indicating an async jump, the process of removing the custom line should be handled by the user of the longjohn module.

The following code illustrates how to update an Error's stack trace, to remove the default line of dashes added by longjohn to indicate an async jump, before reporting the error.

const {ErrorReporting} = require('@google-cloud/error-reporting');

// Instantiates a client
const errors = new ErrorReporting();

const err = new Error('Some Error');
err.stack = (err.stack || '').split('\n')
                            .filter(line => !!line.replace(/-/g, '').trim())
                            .join('\n');
errors.report(err);

The Error Reporting Node.js Client API Reference documentation also contains samples.

Supported Node.js Versions

Our client libraries follow the Node.js release schedule. Libraries are compatible with all current active and maintenance versions of Node.js. If you are using an end-of-life version of Node.js, we recommend that you update as soon as possible to an actively supported LTS version.

Google's client libraries support legacy versions of Node.js runtimes on a best-efforts basis with the following warnings:

Legacy versions are not tested in continuous integration.
Some security patches and features cannot be backported.
Dependencies cannot be kept up-to-date.

Client libraries targeting some end-of-life versions of Node.js are available, and can be installed through npm dist-tags. The dist-tags follow the naming convention legacy-(version). For example, npm install @google-cloud/error-reporting@legacy-8 installs client libraries for versions compatible with Node.js 8.

Versioning

This library follows Semantic Versioning.

This library is considered to be stable. The code surface will not change in backwards-incompatible ways unless absolutely necessary (e.g. because of critical security issues) or with an extensive deprecation period. Issues and requests against stable libraries are addressed with the highest priority.

More Information: Google Cloud Platform Launch Stages

Contributing

Contributions welcome! See the Contributing Guide.

Please note that this README.md, the samples/README.md, and a variety of configuration files in this repository (including .nycrc and tsconfig.json) are generated from a central template. To edit one of these files, make an edit to its templates in directory.