Experimental Client-side JavaScript library for Stackdriver Error Reporting

This is not an official Google product. This module is experimental and may not be ready for use.

This experimental library provides Stackdriver Error Reporting support for client-side web JavaScript 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. For server-side Node.js error reporting, use this other library.

Here's an introductory video:

Prerequisites

1. You need a Google Cloud project.
2. Enable the Stackdriver Error Reporting API for your project. We highly recommend to restrict the usage of the key to your website URL only using an 'HTTP referrer' restriction.
3. Create a browser API key:

• Follow these instructions to get an API key for your project.
• Recommended: Use Application restrictions to restrict this key to your website.
• Recommended: Use API restrictions to limit this key to the Stackdriver Error Reporting API.

If API keys are not an option for your team, you can use a custom url to send your errors to your backend.

Quickstart

Load and initialize the experimental library

Add this line in your HTML code, before </head> and replace <my-api-key> and <my-project-id> with your API key and Google Cloud project ID string:

<!-- Warning: This is an experimental library, do not use it on production environments -->
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/stackdriver-errors-concat.min.js"></script>
<script type="text/javascript">
window.addEventListener('DOMContentLoaded', function() {
  var errorHandler = new StackdriverErrorReporter();
  errorHandler.start({
    key: '<my-api-key>',
    projectId: '<my-project-id>'
  });
});
</script>

And that's all you need to do! Unhandled exceptions will now automatically be reported to your project.

Test your setup

Open the page that you instrumented, open the Devtools console and enter the following to trigger an unhandled exception:

(function testErrorReporting() {window.onerror(null, null, null, null, new Error('Test: Something broke!'));})();

Open Stackdriver Error Reporting at https://console.cloud.google.com/errors to view the error and opt-in to notifications on new errors.

Setup for JavaScript

Download the module

We recommend using npm: npm install stackdriver-errors-js --save.

Initialization

Here are all the initialization options available:

<!-- Warning: This is an experimental library -->
<script defer src="node_modules/stackdriver-errors-js/dist/stackdriver-errors-concat.min.js"></script>
<script type="text/javascript">
window.addEventListener('DOMContentLoaded', function() {
  var errorHandler = new StackdriverErrorReporter();
  errorHandler.start({
    key: '<my-api-key>',
    projectId: '<my-project-id>',
    service: '<my-service>',                    // (optional)
    version: '<my-service-version>',            // (optional)
    // reportUncaughtExceptions: false          // (optional) Set to false to stop reporting unhandled exceptions.
    // reportUnhandledPromiseRejections: false  // (optional) Set to false to stop reporting unhandled promise rejections.
    // disabled: true                           // (optional) Set to true to not report errors when calling report(), this can be used when developing locally.
    // context: {user: 'user1'}                 // (optional) You can set the user later using setUser()
  });
});
</script>

Usage

Unhandled exception will now automatically be reported to Stackdriver Error Reporting.

You can also change your application code to report errors: try { ... } catch(e) { errorHandler.report(e); } or simply errorHandler.report('Something broke!');.

You can set a user identifier at any time using errorHandler.setUser('userId').

Source maps

Only publicly available JavaScript source maps are supported.

Your minified file need to be appended with a comment directive to your source map file:

//# sourceMappingURL=http://example.com/path/to/your/sourcemap.map

Setup for AngularJS

Initialization

1. Load the dist/stackdriver-errors-concat.min.js JavaScript module.

2. Implement a new exception handler for your AngularJS application:

angular.module('myAngularApp', [])

  .factory('$exceptionHandler', ['$log', '$window', function($log, $window) {
    var StackdriverErrors = new $window.StackdriverErrorReporter();
    StackdriverErrors.start({
      key: '<my-api-key>',
      projectId: '<my-project-id>',
      service: '<my-service>',              // (optional)
      version: '<my-service-version>'       // (optional)
    });

    return function(exception, cause) {
      StackdriverErrors.report(exception);
      $log.warn('Reported error:', exception, cause);
    };
  }])

Usage

Uncaught exception in angular expressions will now be reported to Stackdriver Error Reporting.

If you wish, you can manually delegate exceptions, e.g. try { ... } catch(e) { $exceptionHandler(e); } or simply $exceptionHandler('Something broke!');.

Setup for ReactJS

Follow the general instructions denoted in Setup for JavaScript to load and initialize the library.

There is nothing specific that needs to be done with React, other than making sure to initialize the library in your root entry point(typically index.js).

Configuring without an API key

If you are in a situation where an API key is not an option but you already have an acceptable way to communicate with the Stackdriver API (e.g., a secure back end service running in App Engine), you can configure the endpoint that errors are sent to with the following:

const errorHandler = new StackdriverErrorReporter();
errorHandler.start({
  targetUrl: '<my-custom-url>',
  service: '<my-service>',              // (optional)
  version: '<my-service-version>'       // (optional)
});

where targetUrl is the url you'd like to send errors to and can be relative or absolute. This endpoint will need to support the Report API endpoint.

Best Practices

Only reporting in the production environment with Webpack

If using webpack and the DefinePlugin, it is advisable to wrap the initialization logic to only occur in your production environment. Otherwise, with local development you will receive 403s if you restricted your API key to your production environment(which is HIGHLY recommended). The code for this would look something along these lines:

// webpack.production.js
// The rest of your webpack configuration
// ...
plugins: [
    new webpack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify('production')
    }),
  // Your other plugins
]
// ...
// The rest of your webpack configuration

// index.js
const environment = process.env.NODE_ENV;

if (environment === 'production') {
  const errorHandler = new StackdriverErrorReporter();
  errorHandler.start({
    key: '<my-project-id>',
    projectId: '<my-project-id>',
    service: '<my-service>',              // (optional)
    version: '<my-service-version>'       // (optional)
  });
}

Usage as a utility

If you would like to use the error logger throughout your application, there are many options that exist. The simplest is to pull the initialization logic into its own file and reference it as necessary throughout your application as a module. An example would be as follows:

// errorHandlerUtility.js

const environment = process.env.NODE_ENV;

let errorHandler;

if (environment === 'production') {

  errorHandler = new StackdriverErrorReporter();
  errorHandler.start({
    key: '<my-project-id>',
    projectId: '<my-project-id>',
    service: '<my-service>',              // (optional)
    version: '<my-service-version>'       // (optional)
  });

} else {
  errorHandler = {report: console.error};
}

export default errorHandler;

Consumption of the errorHandlerUtility would essentially follow the following pattern:

// MyComponent.jsx
import errorHandler from './errorHandlerUtility';

try {
  someFunctionThatThrows();
} catch (error) {
  errorHandler.report(error);
}

If the call to report has additional levels of wrapping code, extra frames can be trimmed from the top of generated stacks by using a number greater than one for the skipLocalFrames option:

import errorHandler from './errorHandlerUtility';

function backendReport (string) {
  // Skipping the two frames, for report() and for backendReport()
  errorHandler.report(error, {skipLocalFrames: 2});
}

FAQ

Q: Should I use this code in my production application? A: This is an experimental library provided without any guarantee or official support. We do not recommend using it on production without performing a review of its code.

Q: Are private source maps supported? A: No, see #4

Q: Can I propose changes to the library? A: Yes, see the Contributing documentation for more details.