Skip to content
This repository has been archived by the owner on Jul 8, 2020. It is now read-only.

Node.js client for Stackdriver Error Reporting: Count, analyze and aggregate the crashes in your running cloud services.

License

Notifications You must be signed in to change notification settings

DominicKramer/nodejs-error-reporting

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Google Cloud Platform logo

release level npm version codecov

Node.js idiomatic client for Error Reporting.

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

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

  1. Select or create a Cloud Platform project.
  2. Enable the Stackdriver Error Reporting API.
  3. 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

Using the client library

  // Imports the Google Cloud client library
  const {ErrorReporting} = require('@google-cloud/error-reporting');

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

  // Reports a simple error
  errors.report('Something broke!');

This module provides custom Stackdriver Error Reporting support for Node.js applications. Stackdriver 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.

Stackdriver Error Reporting overview

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

Learn about Error Reporting in Stackdriver

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 Stackdriver 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);

Samples

Samples are in the samples/ directory. The samples' README.md has instructions for running the samples.

Sample Source Code Try it
Explicit setup source code Open in Cloud Shell
Express integration source code Open in Cloud Shell
Implicit setup source code Open in Cloud Shell
Manual reporting source code Open in Cloud Shell
Quickstart source code Open in Cloud Shell

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

Versioning

This library follows Semantic Versioning.

This library is considered to be in beta. This means it is expected to be mostly stable while we work toward a general availability release; however, complete stability is not guaranteed. We will address issues and requests against beta libraries with a high priority.

More Information: Google Cloud Platform Launch Stages

Contributing

Contributions welcome! See the Contributing Guide.

License

Apache Version 2.0

See LICENSE

About

Node.js client for Stackdriver Error Reporting: Count, analyze and aggregate the crashes in your running cloud services.

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published

Languages

  • TypeScript 99.3%
  • Other 0.7%