Skip to content

Commit 799bc7a

Browse files
DominicKramerDominicKramer
committed
error-reporting: Address doc inconsistencies
In the README file: * Removed documentation on automatically handling uncaughtExceptions since that logic no longer exists in the code. * Removed the statement saying that this project is not an official Google project. * Added clarity to what configuration is needed in different environments. * Removed an invalid reference to the Stackdriver Trace agent for Node.js. * Did some refactoring to make the documentation easier to read.
1 parent 7635251 commit 799bc7a

1 file changed

Lines changed: 32 additions & 25 deletions

File tree

‎packages/error-reporting/README.md‎

Lines changed: 32 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
# Node.js module for Stackdriver Error Reporting
1+
# Stackdriver Error Reporting for Node.js
22

33
[![NPM Version][npm-image]][npm-url]
44
[![Known Vulnerabilities][snyk-image]][snyk-url]
55

6-
> **This is not an official Google product.** This module is experimental and may not be ready for use.
6+
> This module is experimental, and should be used by early adopters.
77
> This module uses APIs that may be undocumented and are subject to change without notice.
88
99
This module provides Stackdriver Error Reporting support for Node.js applications.
@@ -16,11 +16,12 @@ applications running in almost any environment. Here's an introductory video:
1616
## Prerequisites
1717

1818
1. Your application needs to use Node.js version 4.x or greater.
19-
1. You need a [Google Cloud project](https://console.cloud.google.com). Your application can run anywhere, but errors are reported to a particular project.
20-
1. [Enable the Stackdriver Error Reporting API](https://console.cloud.google.com/apis/api/clouderrorreporting.googleapis.com/overview) for your project.
21-
1. The module will only send errors when the `NODE_ENV` environment variable is
19+
2. You need a [Google Cloud project](https://console.cloud.google.com). Your application can run anywhere, but errors are reported to a particular project.
20+
3. [Enable the Stackdriver Error Reporting API](https://console.cloud.google.com/apis/api/clouderrorreporting.googleapis.com/overview) for your project.
21+
22+
**Note:** The module will only send errors when the `NODE_ENV` environment variable is
2223
set to `production` or the `ignoreEnvironmentCheck` property given in the
23-
runtime configuration object is set to `true`.
24+
runtime configuration object is set to `true`. See the [Configuration](#configuration) section for more details.
2425

2526
## Quick Start
2627

@@ -33,7 +34,7 @@ runtime configuration object is set to `true`.
3334
npm install --save @google-cloud/error-reporting
3435
```
3536

36-
2. **Instrument your application:**
37+
2. **Require the module:**
3738

3839
```js
3940
// Require the library and initialize the error handler
@@ -45,9 +46,13 @@ var errors = require('@google-cloud/error-reporting')({
4546
errors.report(new Error('Something broke!'));
4647
```
4748

48-
- **One may even catch and report application-wide uncaught errors:**
49-
- *It is recommended to catch uncaughtExceptions for production-deployed applications.*
50-
- To read more about uncaught exception handling in Node.js and what it means for your application [please click here](https://nodejs.org/api/process.html#process_event_uncaughtexception).
49+
3. **View reported errors:**
50+
51+
Open Stackdriver Error Reporting at https://console.cloud.google.com/errors to view the reported errors.
52+
53+
## Catching and Reporting Application-wide Uncaught Errors
54+
55+
*It is recommended to catch `uncaughtExceptions` for production-deployed applications.*
5156

5257
```js
5358
var errors = require('@google-cloud/error-reporting')();
@@ -59,12 +64,12 @@ process.on('uncaughtException', (e) => {
5964
});
6065
```
6166

62-
3. **View reported errors:**
63-
64-
Open Stackdriver Error Reporting at https://console.cloud.google.com/errors to view the reported errors.
67+
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).
6568

6669
## Running on Google Cloud Platform
6770

71+
All information in this section assumes that the items in the [Prerequisites](#prerequisites) section above have been completed.
72+
6873
### Google App Engine Flexible environment
6974

7075
If you are using [Google App Engine flexible environment](https://cloud.google.com/appengine/docs/flexible/), you do not have to do any additional configuration.
@@ -84,14 +89,14 @@ Container Engine nodes need to also be created with the `https://www.googleapis.
8489
If your application is running outside of Google Cloud Platform, such as locally, on-premise, or on another cloud provider, you can still use Stackdriver Errors.
8590

8691
1. You will need to specify your project ID when starting the errors agent.
87-
88-
GCLOUD_PROJECT=particular-future-12345 node myapp.js
89-
90-
1. You need to provide service account credentials to your application.
92+
```
93+
GCLOUD_PROJECT=particular-future-12345 node myapp.js
94+
```
95+
2. You need to provide service account credentials to your application by using one of the three options below:
9196
* The recommended way is via [Application Default Credentials][app-default-credentials].
9297
1. [Create a new JSON service account key][service-account].
93-
1. Copy the key somewhere your application can access it. Be sure not to expose the key publicly.
94-
1. Set the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to the full path to the key. The trace agent will automatically look for this environment variable.
98+
2. Copy the key somewhere your application can access it. Be sure not to expose the key publicly.
99+
3. Set the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to the full path to the key. The Error Reporting library will automatically look for this environment variable.
95100
* If you are running your application on a development machine or test environment where you are using the [`gcloud` command line tools][gcloud-sdk], and are logged using `gcloud beta auth application-default login`, you already have sufficient credentials, and a service account key is not required.
96101
* Alternatively, you may set the `keyFilename` or `credentials` configuration field to the full path or contents to the key file, respectively. Setting either of these fields will override either setting `GOOGLE_APPLICATION_CREDENTIALS` or logging in using `gcloud`. For example:
97102

@@ -110,7 +115,7 @@ When running on Google Cloud Platform, we handle these for you automatically.
110115

111116
## Configuration
112117

113-
The following code snippet lists all available configuration options. All configuration options are optional.
118+
The following code snippet lists all available configuration options. Except for the `keyFilename` and `credentials` options, all configuration options are optional. Whether or not the `keyFilename` and `credentials` options are required is outlined in the [Running on Google Cloud Platform](#running-on-google-cloud-platform) section above.
114119

115120
```js
116121
var errors = require('@google-cloud/error-reporting')({
@@ -121,10 +126,9 @@ var errors = require('@google-cloud/error-reporting')({
121126
// of the value of NODE_ENV
122127
// defaults to false
123128
ignoreEnvironmentCheck: false,
124-
// determines if the library will attempt to report uncaught exceptions
125-
// defaults to true
126-
reportUncaughtExceptions: true,
127129
// determines the logging level internal to the library; levels range 0-5
130+
// where 0 indicates no logs should be reported and 5 indicates all logs
131+
// should be reported
128132
// defaults to 2 (warnings)
129133
logLevel: 2,
130134
serviceContext: {
@@ -140,13 +144,16 @@ var errors = require('@google-cloud/error-reporting')({
140144

141145
```js
142146
var errors = require('@google-cloud/error-reporting')();
147+
143148
// Use the error message builder to custom set all message fields
144149
var errorEvt = errors.event()
145-
.setMessage('My error message')
146-
.setUser('root@nexus');
150+
.setMessage('My error message')
151+
.setUser('root@nexus');
147152
errors.report(errorEvt, () => console.log('done!'));
153+
148154
// Or just use a regular error
149155
errors.report(new Error('My error message'), () => console.log('done!'));
156+
150157
// One can even just use a string
151158
errors.report('My error message');
152159
```

0 commit comments

Comments
 (0)