Skip to content

Commit

Permalink
chore(docs): Update .readme-partials.yaml
Browse files Browse the repository at this point in the history 
Removed out-dated code samples and pointed the README towards the https://cloud.google.com/error-reporting/docs/setup/nodejs documentation instead.
  • Loading branch information
@meredithslota
meredithslota authored Oct 18, 2023
1 parent baf6b8e commit d217c75
Showing 1 changed file with 4 additions and 252 deletions.
256 changes: 4 additions & 252 deletions .readme-partials.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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

0 comments on commit d217c75

Please sign in to comment.