{"id":13468658,"url":"https://github.com/GoogleCloudPlatform/stackdriver-errors-js","last_synced_at":"2025-03-26T05:31:14.876Z","repository":{"id":37444663,"uuid":"64250606","full_name":"GoogleCloudPlatform/stackdriver-errors-js","owner":"GoogleCloudPlatform","description":"Client-side JavaScript exception reporting library for Cloud Error Reporting","archived":false,"fork":false,"pushed_at":"2024-10-11T18:32:49.000Z","size":2688,"stargazers_count":362,"open_issues_count":36,"forks_count":54,"subscribers_count":28,"default_branch":"master","last_synced_at":"2024-10-29T15:48:11.261Z","etag":null,"topics":["client-side","crash-reporting","error-monitoring","javascript","stackdriver"],"latest_commit_sha":null,"homepage":"https://cloud.google.com/error-reporting/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GoogleCloudPlatform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-26T20:02:40.000Z","updated_at":"2024-09-07T02:48:07.000Z","dependencies_parsed_at":"2024-06-18T13:44:06.393Z","dependency_job_id":"f0886d28-e6cf-4b13-b4d7-4a0f5994fc6c","html_url":"https://github.com/GoogleCloudPlatform/stackdriver-errors-js","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fstackdriver-errors-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fstackdriver-errors-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fstackdriver-errors-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fstackdriver-errors-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GoogleCloudPlatform","download_url":"https://codeload.github.com/GoogleCloudPlatform/stackdriver-errors-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245597269,"owners_count":20641862,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client-side","crash-reporting","error-monitoring","javascript","stackdriver"],"created_at":"2024-07-31T15:01:15.991Z","updated_at":"2025-03-26T05:31:13.374Z","avatar_url":"https://github.com/GoogleCloudPlatform.png","language":"JavaScript","readme":"# Experimental Client-side JavaScript library for Cloud Error Reporting\n\n\u003e **This is not an official Google product.** This module is experimental and may not be ready for use.\n\nThis **experimental** library provides Cloud Error Reporting support for client-side web JavaScript applications. [Cloud Error Reporting](https://cloud.google.com/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 [cloud-errors-nodejs](https://github.com/GoogleCloudPlatform/cloud-errors-nodejs) instead.\n\nHere's an introductory video:\n\n[![Learn about Cloud Error Reporting][video thumbnail]][video link]\n\n## Prerequisites\n\n1. You need a [Google Cloud project](https://console.cloud.google.com).\n\n2. [Enable the Cloud Error Reporting API](https://console.cloud.google.com/apis/api/clouderrorreporting.googleapis.com/overview) for your project. We highly recommend to restrict the usage of the key to your website URL only using an 'HTTP referrer' restriction.\n\n3. Create a browser API key:\n   - Follow [using api keys instructions](https://support.google.com/cloud/answer/6158862) to get an API key for your project.\n   - Recommended: Use **Application restrictions** to restrict this key to your website.\n   - Recommended: Use **API restrictions** to limit this key to the *Cloud Error Reporting API*.\n\nIf API keys are not an option for your team, [use a custom url](\n#configuring-without-an-api-key) to send your errors to your backend.\n\n## Quickstart\n\nThe library can either be used as a standalone script, or incorporated as a module into a larger javascript application.\n\nFor use in any HTML page or without a specific framework, include the standalone script from CDN and set up the error handler in a page load event.\nFor instance, use include the following HTML in the page `\u003chead\u003e` and replace:\n\n* `\u003cversion\u003e` with the [latest version of the NPM package](https://www.npmjs.com/package/stackdriver-errors-js) \n* `\u003cmy-api-key\u003e` with your API key\n* `\u003cmy-project-id\u003e` with  and Google Cloud project ID string:\n\n```HTML\n\u003c!-- Warning: Experimental library, do not use in production environments. --\u003e\n\u003cscript defer src=\"https://cdn.jsdelivr.net/npm/stackdriver-errors-js@\u003cversion\u003e/dist/stackdriver-errors-concat.min.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\"\u003e\nwindow.addEventListener('DOMContentLoaded', function() {\n  var errorHandler = new StackdriverErrorReporter();\n  errorHandler.start({\n    key: '\u003cmy-api-key\u003e',\n    projectId: '\u003cmy-project-id\u003e'\n    // Other optional arguments can also be supplied, see below.\n  });\n});\n\u003c/script\u003e\n```\nAnd that's all you need to do! Unhandled exceptions will now automatically be reported to your project.\n\n### Test your setup\n\nOpen the page that you instrumented, open the Developer Tools console and enter the following to trigger an unhandled exception:\n\n```javascript\n(function testErrorReporting() {\n  window.onerror(null, null, null, null, new Error('Test: Something broke!'));\n})();\n```\n\nOpen [Cloud Error Reporting](https://console.cloud.google.com/errors) to view the error and opt-in to notifications on new errors.\n\n\n## Setup for JavaScript\n\n### Installing\n\nWe recommend using npm: `npm install stackdriver-errors-js --save`.\n\n### Initialization\n\nCreate a file that is included in your application entry point and has access to variables `myApiKey` and `myProjectId`. For ES6 projects it can be in the form:\n\n```javascript\n// Warning: Experimental library, do not use in production environments.\nimport StackdriverErrorReporter from 'stackdriver-errors-js';\n\nconst errorHandler = new StackdriverErrorReporter();\nerrorHandler.start({\n    key: myApiKey,\n    projectId: myProjectId,\n\n    // The following optional arguments can also be provided:\n\n    // service: myServiceName,\n    // Name of the service reporting the error, defaults to 'web'.\n\n    // version: myServiceVersion,\n    // Version identifier of the service reporting the error.\n\n    // reportUncaughtExceptions: false\n    // Set to false to prevent reporting unhandled exceptions, default: `true`.\n\n    // reportUnhandledPromiseRejections: false\n    // Set to false to prevent reporting unhandled promise rejections, default: `true`.\n\n    // disabled: true\n    // Set to true to not send error reports, this can be used when developing locally, default: `false`.\n\n    // context: {user: 'user1'}\n    // You can set the user later using setUser()\n});\n```\n\nNote this uses the ES6 import syntax, if your project does not use a compilation step, instead the source with dependencies and polyfills bundled can be used directly:\n\n```javascript\nvar StackdriverErrorReporter = require('stackdriver-errors-js/dist/stackdriver-errors-concat.min.js');\n\nvar errorHandler = new StackdriverErrorReporter();\nerrorHandler.start({\n    key: myApiKey,\n    projectId: myProjectId,\n    // Other optional arguments can be supplied, see above.\n});\n```\n\n### Usage\n\nUnhandled exception will now automatically be sent to Stackdriver Error Reporting.\n\nYou can also change your application code to report errors:\n\n```javascript\ntry {\n  ...\n} catch(e) {\n  errorHandler.report(e);\n}\n```\n\nOr simply:\n\n```javascript\nerrorHandler.report('Something broke!');\n```\n\nYou can set a user identifier at any time using:\n\n```javascript\nerrorHandler.setUser('userId')\n```\n\n## Setup for AngularJS\n\n### Initialization\n\n1. Load the `dist/stackdriver-errors-concat.min.js` JavaScript module.\n\n2. Implement a new [AngularJS exception handler](https://docs.angularjs.org/api/ng/service/$exceptionHandler) for your application:\n\n```javascript\nangular.module('myAngularApp', [])\n\n  .factory('$exceptionHandler', ['$log', '$window', function($log, $window) {\n    var StackdriverErrors = new $window.StackdriverErrorReporter();\n    StackdriverErrors.start({\n      key: '\u003cmy-api-key\u003e',\n      projectId: '\u003cmy-project-id\u003e',\n      // Other optional arguments can be supplied, see above.\n    });\n\n    return function(exception, cause) {\n      StackdriverErrors.report(exception);\n      $log.warn('Reported error:', exception, cause);\n    };\n  }])\n```\n\n### Usage\n\nUncaught exception in angular expressions will now be reported to Stackdriver Error Reporting.\n\nIf you wish, you can manually delegate exceptions, for instance:\n```javascript\ntry { ... } catch(e) { $exceptionHandler(e); }\n```\nOr simply:\n```javascript\n$exceptionHandler('Something broke!');\n```\n\n## Setup for ReactJS\n\nFollow the general instructions denoted in _Setup for JavaScript_ to load and initialize the library.\n\nThere 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`).\n\n## Source maps\n\nOnly publicly available JavaScript source maps are supported.\n\nYour minified file need to be appended with a comment directive to your source map file:\n\n```javascript\n//# sourceMappingURL=http://example.com/path/to/your/sourcemap.map\n```\n\n## Configuring without an API key\n\nIf 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:\n\n```javascript\nconst errorHandler = new StackdriverErrorReporter();\nerrorHandler.start({\n  targetUrl: '\u003cmy-custom-url\u003e',\n  service: '\u003cmy-service\u003e',              // (optional)\n  version: '\u003cmy-service-version\u003e'       // (optional)\n});\n```\n\nwhere `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](https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report).\n\n## Custom message dispatching\n\nIf you can't use HTTP Post requests for reporting your errors, or in need for some more complicated customizations, you may provide a custom function to handle the reporting.\n\nThe function will be called with a payload argument (the same one that would have been sent on the HTTP Post request) and should return a Promise.  \n\n```javascript\nconst errorHandler = new StackdriverErrorReporter();\nfunction myCustomFunction(payload) {\n  console.log(\"custom reporting function called with payload:\", payload);\n  return Promise.resolve(); \n}\nerrorHandler.start({\n  customReportingFunction: myCustomFunction,\n});\n```\n\n## Best Practices\n\n### Only reporting in the production environment with Webpack\n\nIf 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:\n\n```javascript\n// webpack.production.js\n\nmodule.exports = {\n  // ...\n  plugins: [\n    new webpack.DefinePlugin({\n      'process.env.NODE_ENV': JSON.stringify('production')\n    }),\n  ],\n  // ...\n}\n```\n\n```javascript\n// index.js\n\nif (process.env.NODE_ENV === 'production') {\n  const errorHandler = new StackdriverErrorReporter();\n  errorHandler.start({\n    key: '\u003cmy-project-id\u003e',\n    projectId: '\u003cmy-project-id\u003e',\n  });\n}\n```\n\n### Usage as a utility\n\nIf 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:\n\n```javascript\n// errorHandlerUtility.js\nimport StackdriverErrorReporter from 'stackdriver-errors-js';\n\nlet errorHandler;\n\nif (process.env.NODE_ENV === 'production') {\n  errorHandler = new StackdriverErrorReporter();\n  errorHandler.start({\n    key: '\u003cmy-project-id\u003e',\n    projectId: '\u003cmy-project-id\u003e',\n    // Other optional arguments can be supplied, see above.\n  });\n} else {\n  errorHandler = {report: console.error};\n}\n\nexport default errorHandler;\n```\n\nConsumption of `errorHandlerUtility` would essentially follow the following pattern:\n\n```javascript\nimport errorHandler from './errorHandlerUtility';\n\ntry {\n  someFunctionThatThrows();\n} catch (error) {\n  errorHandler.report(error);\n}\n```\n\nIf 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:\n\n```javascript\nimport errorHandler from './errorHandlerUtility';\n\nfunction backendReport (string) {\n  // Skipping the two frames, for report() and for backendReport()\n  errorHandler.report(error, {skipLocalFrames: 2});\n}\n```\n\n## FAQ\n\n**Q: Should I use this code in my production application?**\nA: 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.\n\n**Q: Are private source maps supported?**\nA: No, see [issue #4](https://github.com/GoogleCloudPlatform/stackdriver-errors-js/issues/4).\n\n**Q: Can I propose changes to the library?**\nA: Yes, see [the Contributing documentation](CONTRIBUTING.md) for more details.\n\n\n[video thumbnail]: https://img.youtube.com/vi/cVpWVD75Hs8/0.jpg\n[video link]: https://www.youtube.com/watch?v=cVpWVD75Hs8\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGoogleCloudPlatform%2Fstackdriver-errors-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGoogleCloudPlatform%2Fstackdriver-errors-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGoogleCloudPlatform%2Fstackdriver-errors-js/lists"}