Name: stackdriver-errors-js
Owner: Google Cloud Platform
Description: Client-side JavaScript exception reporting library for Stackdriver Error Reporting
Created: 2016-07-26 20:02:40.0
Updated: 2018-05-15 21:32:30.0
Pushed: 2017-12-20 06:25:18.0
Homepage: https://cloud.google.com/error-reporting/
Size: 611
Language: JavaScript
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
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:
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 -->
ipt defer src="https://cdn.rawgit.com/GoogleCloudPlatform/stackdriver-errors-js/v0.4.0/dist/stackdriver-errors-concat.min.js"></script>
ipt type="text/javascript">
ow.addEventListener('DOMContentLoaded', function() {
r errorHandler = new StackdriverErrorReporter();
rorHandler.start({
key: '<my-api-key>',
projectId: '<my-project-id>'
;
ript>
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:
ction 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.
We recommend using npm: npm install stackdriver-errors-js --save
.
Here are all the initialization options available:
Warning: This is an experimental library -->
ipt defer src="node_modules/stackdriver-errors-js/dist/stackdriver-errors-concat.min.js"></script>
ipt type="text/javascript">
ow.addEventListener('DOMContentLoaded', function() {
r errorHandler = new StackdriverErrorReporter();
rorHandler.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.
// disabled: true // (optional) Set to true to not report errors when calling report(), this can be used when developping locally.
// context: {user: 'user1'} // (optional) You can set the user later using setUser()
;
ript>
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')
.
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
Load the dist/stackdriver-errors-concat.min.js
JavaScript module.
Implement a new exception handler for your AngularJS application:
lar.module('myAngularApp', [])
actory('$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);
};
)
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!');
.
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
).
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:
t errorHandler = new StackdriverErrorReporter();
rHandler.start({
rgetUrl: '<my-custom-url>',
rvice: '<my-service>', // (optional)
rsion: '<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.
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:
ebpack.production.js
he rest of your webpack configuration
..
ins: [
new webpack.DefinePlugin({
'process.env.NODE_ENV': JSON.stringify('production')
}),
Your other plugins
..
he rest of your webpack configuration
avascript
ndex.js
t environment = process.env.NODE_ENV;
environment === 'production') {
nst errorHandler = new StackdriverErrorReporter();
rorHandler.start({
key: '<my-project-id>',
projectId: '<my-project-id>',
service: '<my-service>', // (optional)
version: '<my-service-version>' // (optional)
;
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:
rrorHandlerUtility.js
t environment = process.env.NODE_ENV;
errorHandler;
environment === 'production') {
rorHandler = new StackdriverErrorReporter();
rorHandler.start({
key: '<my-project-id>',
projectId: '<my-project-id>',
service: '<my-service>', // (optional)
version: '<my-service-version>' // (optional)
;
se {
rorHandler = console.error;
rt default errorHandler;
Consumption of the errorHandlerUtility would essentially follow the following pattern:
yComponent.jsx
rt errorHandler from './errorHandlerUtility';
ome example code that throws an error
ch(error) {
rorHandler.report(error);
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
Install developer dependencies with npm install --dev
npm test
or yarn run test
to test your changes.npm run dist
or yarn run dist
generates the minified version.Start a web server at the root of this repo and open demo/demo.html
to test reporting errors from the local library with your API key and project ID.
git tag v0.0.x
git push --tags
npm publish