From d217c750af8b493d1ee5654a8fa24ecb52243d65 Mon Sep 17 00:00:00 2001 From: meredithslota Date: Wed, 18 Oct 2023 16:53:33 -0700 Subject: [PATCH 1/2] chore(docs): Update .readme-partials.yaml Removed out-dated code samples and pointed the README towards the https://cloud.google.com/error-reporting/docs/setup/nodejs documentation instead. --- .readme-partials.yaml | 256 +----------------------------------------- 1 file changed, 4 insertions(+), 252 deletions(-) diff --git a/.readme-partials.yaml b/.readme-partials.yaml index f9da2d40b..b158b6364 100644 --- a/.readme-partials.yaml +++ b/.readme-partials.yaml @@ -15,10 +15,6 @@ body: |- ![Error Reporting overview](https://raw.githubusercontent.com/googleapis/nodejs-error-reporting/master/doc/images/errors-overview.png) - Here's an introductory video that provides some more details: - - [![Learn about Error Reporting in Google Cloud](https://img.youtube.com/vi/cVpWVD75Hs8/0.jpg)](https://www.youtube.com/watch?v=cVpWVD75Hs8) - # 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: @@ -32,252 +28,8 @@ body: |- * `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](#configuration) section to learn how to specify configuration options. - - ## Configuration - The following code snippet lists available configuration options. All configuration options are optional. - - ```js - 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 - - ```js - 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 - - ```js - 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 - - ```js - 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 - - ```js - 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 - - ```js - 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](#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 `uncaughtException`s 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 `uncaughtException`s to be reported manually. - - ```js - 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 Cloud 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](https://nodejs.org/api/process.html#process_event_uncaughtexception). - - ### Using an API Key - - You may use an API key in lieu of locally-stored credentials. Please see [this document](https://support.google.com/cloud/answer/6158862) 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: - - ```js - 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](https://www.npmjs.com/package/longjohn) module can be used with this library to enable [long-stack-traces](https://github.com/tlrobinson/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. - ```js - const {ErrorReporting} = require('@google-cloud/error-reporting'); - - // Instantiates a client - const errors = new ErrorReporting(); + ## Setup, Configuration, and Examples - const err = new Error('Some Error'); - err.stack = (err.stack || '').split('\n') - .filter(line => !!line.replace(/-/g, '').trim()) - .join('\n'); - errors.report(err); - ``` + See the documentation for setup instructions, configuration options, and examples: https://cloud.google.com/error-reporting/docs/setup/nodejs + + Additional code samples can also be found here: https://github.com/GoogleCloudPlatform/nodejs-docs-samples/tree/main/error-reporting From 12710ea32181382e3e908eb93bd76e3b40ac31f1 Mon Sep 17 00:00:00 2001 From: Owl Bot Date: Wed, 18 Oct 2023 23:56:14 +0000 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=A6=89=20Updates=20from=20OwlBot=20po?= =?UTF-8?q?st-processor?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --- README.md | 254 +----------------------------------------------------- 1 file changed, 3 insertions(+), 251 deletions(-) diff --git a/README.md b/README.md index 672757955..161cc6a2b 100644 --- a/README.md +++ b/README.md @@ -65,10 +65,6 @@ Thus, if you are already using Winston or Bunyan in your application, and don't ![Error Reporting overview](https://raw.githubusercontent.com/googleapis/nodejs-error-reporting/master/doc/images/errors-overview.png) -Here's an introductory video that provides some more details: - -[![Learn about Error Reporting in Google Cloud](https://img.youtube.com/vi/cVpWVD75Hs8/0.jpg)](https://www.youtube.com/watch?v=cVpWVD75Hs8) - # 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: @@ -82,255 +78,11 @@ The `ignoreEnvironmentCheck` option should not be used. However, if it is used, * `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](#configuration) section to learn how to specify configuration options. - -## Configuration -The following code snippet lists available configuration options. All configuration options are optional. - -```js -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 - -```js -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 - -```js -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 - -```js -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 - -```js -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); -}); +## Setup, Configuration, and Examples -// response -app.use(function *(){ - this.body = 'Hello World'; -}); +See the documentation for setup instructions, configuration options, and examples: https://cloud.google.com/error-reporting/docs/setup/nodejs -app.listen(3000); -``` - -### Using Restify - -```js -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](#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 `uncaughtException`s 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 `uncaughtException`s to be reported manually. - -```js -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 Cloud 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](https://nodejs.org/api/process.html#process_event_uncaughtexception). - -### Using an API Key - -You may use an API key in lieu of locally-stored credentials. Please see [this document](https://support.google.com/cloud/answer/6158862) 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: - -```js -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](https://www.npmjs.com/package/longjohn) module can be used with this library to enable [long-stack-traces](https://github.com/tlrobinson/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. -```js -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); -``` +Additional code samples can also be found here: https://github.com/GoogleCloudPlatform/nodejs-docs-samples/tree/main/error-reporting