Error Reporting: Node.js Client

Node.js idiomatic client forError Reporting.

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

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

• Error Reporting Node.js Client API Reference
• Error Reporting Documentation
• github.com/googleapis/nodejs-error-reporting

Read more about the client libraries for Cloud APIs, including the olderGoogle APIs Client Libraries, inClient Libraries Explained.

Table of contents:

• Quickstart
  • Before you begin
  • Installing the client library
  • Using the client library
• Samples
• Versioning
• Contributing
• License

Quickstart

Before you begin

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

Installing the client library

npm install @google-cloud/error-reporting

Using the client library

// Imports the Google Cloud client libraryconst {ErrorReporting} = require('@google-cloud/error-reporting');// Instantiates a clientconst errors = newErrorReporting();// Reports a simple errorerrors.report('Something broke!');

This module provides custom Error Reporting support for Node.js applications.Error Reporting is a feature ofGoogle Cloud Platform that allows in-depth monitoring and viewing of errors reported byapplications 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 severityerror 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.

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

When Errors Are Reported

ThereportMode 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.

ThereportMode configuration option replaces the deprecatedignoreEnvironmentCheck configuration option. If both thereportMode andignoreEnvironmentCheck options are specified, thereportMode configuration option takes precedence.

TheignoreEnvironmentCheck option should not be used. However, if it is used, and thereportMode 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 theConfiguration 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 clientconst errors = newErrorReporting({    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 clientconst errors = newErrorReporting();// 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 theerrors.report method is given anErrorMessage object built using theerrors.event method, the stack trace at the point where the error event was constructed will be used.
• If theerrors.report method is given anError object, the stack trace where the error was instantiated will be used.
• If theerrors.report method is given a string, the stack trace at the point whereerrors.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 clientconst errors = newErrorReporting();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 clientconst errors = newErrorReporting();const server = newhapi.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 clientconst errors = newErrorReporting();const app = new Koa();app.use(errors.koa);app.use(function *(next) {    //This will set status and message    this.throw('Error Message', 500);});// responseapp.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 clientconst errors = newErrorReporting();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 thereportUnhandledRejections configuration option. See theConfiguration 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 processuncaughtExceptions for production-deployed applications.

Note that uncaught exceptions are not reported by default because to do so would require adding a listener to theuncaughtException event. Adding such a listener without knowledge of otheruncaughtException listeners can cause interference between the event handlers or prevent the process from terminating cleanly. As such, it is necessary foruncaughtExceptions 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 clientconst errors = newErrorReporting();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 foundhere.

Using an API Key

You may use an API key in lieu of locally-stored credentials. Please seethis 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 clientconst errors = newErrorReporting({    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

Thelongjohn module can be used with this library to enablelong-stack-traces and updates anError object's stack trace, by adding special line, to indicate an async jump. Inlongjohn version0.2.12, for example, a single line of dashes is included in a stack trace, by default, to indicate an async jump.

Before reporting anError object using thereport method of the@google-cloud/error-reporting module, the stack trace needs to modified to remove this special line added bylongjohn. Since thelongjohn 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 thelongjohn module.

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

const {ErrorReporting} = require('@google-cloud/error-reporting');// Instantiates a clientconst errors = newErrorReporting();const err = new Error('Some Error');err.stack = (err.stack || '').split('\n')                            .filter(line => !!line.replace(/-/g, '').trim())                            .join('\n');errors.report(err);

Samples

Samples are in thesamples/ directory. Each sample'sREADME.md has instructions for running its sample.

Sample	Source Code	Try it
Explicit setup	source code
Express integration	source code
Implicit setup	source code
Manual reporting	source code
Quickstart	source code

TheError Reporting Node.js Client API Reference documentationalso contains samples.

Supported Node.js Versions

Our client libraries follow theNode.js release schedule.Libraries are compatible with all currentactive andmaintenance versions ofNode.js.If you are using an end-of-life version of Node.js, we recommend that you updateas soon as possible to an actively supported LTS version.

Google's client libraries support legacy versions of Node.js runtimes on abest-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, andcan be installed through npmdist-tags.The dist-tags follow the naming conventionlegacy-(version).For example,npm install @google-cloud/error-reporting@legacy-8 installs client librariesfor versions compatible with Node.js 8.

Versioning

This library followsSemantic Versioning.

This library is considered to bestable. The code surface will not change in backwards-incompatible waysunless absolutely necessary (e.g. because of critical security issues) or withan extensive deprecation period. Issues and requests againststable librariesare addressed with the highest priority.

More Information:Google Cloud Platform Launch Stages

Contributing

Contributions welcome! See theContributing Guide.

Please note that thisREADME.md, thesamples/README.md,and a variety of configuration files in this repository (including.nycrc andtsconfig.json)are generated from a central template. To edit one of these files, make an editto its templates indirectory.

License

Apache Version 2.0

SeeLICENSE