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