Skip to content

Commit c0fab9d

Browse files
bz2bz2
authored
Update README (#66)
Tidy up markdown formatting, including moving some links to the end in reference form. Rework the setup examples and show ES6 form as an option. Reword some text for clarity.
1 parent a0258b7 commit c0fab9d

File tree

1 file changed

+134
-84
lines changed

1 file changed

+134
-84
lines changed

‎README.md‎

Lines changed: 134 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -2,126 +2,161 @@
22

33
> **This is not an official Google product.** This module is experimental and may not be ready for use.
44
5-
[![Build Status](https://travis-ci.org/GoogleCloudPlatform/stackdriver-errors-js.svg?branch=master)](https://travis-ci.org/GoogleCloudPlatform/stackdriver-errors-js)
6-
[![Dependency Status](https://david-dm.org/GoogleCloudPlatform/stackdriver-errors-js.svg)](https://david-dm.org/GoogleCloudPlatform/stackdriver-errors-js)
5+
[![Build Status][travis-ci status image]][travis-ci status link]
6+
[![Dependency Status][david-dm status image]][david-dm status link]
77

8-
This **experimental** library provides Stackdriver Error Reporting support for client-side web JavaScript applications.
9-
[Stackdriver 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 [this other library](https://github.com/GoogleCloudPlatform/cloud-errors-nodejs).
8+
This **experimental** library provides Stackdriver Error Reporting support for client-side web JavaScript applications. [Stackdriver 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.
109

1110
Here's an introductory video:
1211

13-
[![Learn about Error Reporting in Stackdriver](https://img.youtube.com/vi/cVpWVD75Hs8/0.jpg)](https://www.youtube.com/watch?v=cVpWVD75Hs8)
12+
[![Learn about Error Reporting in Stackdriver][video thumbnail]][video link]
1413

1514
## Prerequisites
1615

1716
1. You need a [Google Cloud project](https://console.cloud.google.com).
18-
1. [Enable the Stackdriver 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.
19-
1. Create a browser API key:
2017

21-
- Follow [these instructions](https://support.google.com/cloud/answer/6158862) to get an API key for your project.
22-
- Recommended: Use **Application restrictions** to restrict this key to your website.
23-
- Recommended: Use **API restrictions** to limit this key to the *Stackdriver Error Reporting API*.
18+
2. [Enable the Stackdriver 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.
2419

25-
If API keys are not an option for your team, you can [use a custom url](#configuring-without-an-api-key) to send your errors to your backend.
20+
3. Create a browser API key:
21+
- Follow [using api keys instructions](https://support.google.com/cloud/answer/6158862) to get an API key for your project.
22+
- Recommended: Use **Application restrictions** to restrict this key to your website.
23+
- Recommended: Use **API restrictions** to limit this key to the *Stackdriver Error Reporting API*.
24+
25+
If API keys are not an option for your team, [use a custom url](
26+
#configuring-without-an-api-key) to send your errors to your backend.
2627

2728
## Quickstart
2829

29-
**Load and initialize the experimental library**
30+
The library can either be used as a standalone script, or incorporated as a module into a larger javascript application.
3031

31-
Add this line in your HTML code, before `</head>` and replace `<my-api-key>` and `<my-project-id>` with your API key and Google Cloud project ID string:
32+
For 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. For instance, use include the following HTML in the page `<head>` and replace `<my-api-key>` and `<my-project-id>` with your API key and Google Cloud project ID string:
3233

3334
```HTML
34-
<!-- Warning: This is an experimental library, do not use it on production environments -->
35+
<!-- Warning: Experimental library, do not use in production environments. -->
3536
<script defer src="https://cdn.jsdelivr.net/npm/stackdriver-errors-js@0.7.0/dist/stackdriver-errors-concat.min.js"></script>
3637
<script type="text/javascript">
3738
window.addEventListener('DOMContentLoaded', function() {
3839
var errorHandler = new StackdriverErrorReporter();
3940
errorHandler.start({
4041
key: '<my-api-key>',
4142
projectId: '<my-project-id>'
43+
// Other optional arguments can also be supplied, see below.
4244
});
4345
});
4446
</script>
4547
```
4648
And that's all you need to do! Unhandled exceptions will now automatically be reported to your project.
4749

48-
**Test your setup**
50+
### Test your setup
4951

50-
Open the page that you instrumented, open the Devtools console and enter the following to trigger an unhandled exception:
52+
Open the page that you instrumented, open the Developer Tools console and enter the following to trigger an unhandled exception:
5153

52-
```JS
53-
(function testErrorReporting() {window.onerror(null, null, null, null, new Error('Test: Something broke!'));})();
54+
```javascript
55+
(function testErrorReporting() {
56+
window.onerror(null, null, null, null, new Error('Test: Something broke!'));
57+
})();
5458
```
5559

56-
Open Stackdriver Error Reporting at https://console.cloud.google.com/errors to view the error and opt-in to notifications on new errors.
60+
Open [Stackdriver Error Reporting](https://console.cloud.google.com/errors) to view the error and opt-in to notifications on new errors.
5761

5862

5963
## Setup for JavaScript
6064

61-
### Download the module
65+
### Installing
6266

6367
We recommend using npm: `npm install stackdriver-errors-js --save`.
6468

6569
### Initialization
6670

67-
Here are all the initialization options available:
71+
Create 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:
6872

69-
```HTML
70-
<!-- Warning: This is an experimental library -->
71-
<script defer src="node_modules/stackdriver-errors-js/dist/stackdriver-errors-concat.min.js"></script>
72-
<script type="text/javascript">
73-
window.addEventListener('DOMContentLoaded', function() {
74-
var errorHandler = new StackdriverErrorReporter();
75-
errorHandler.start({
76-
key: '<my-api-key>',
77-
projectId: '<my-project-id>',
78-
service: '<my-service>', // (optional)
79-
version: '<my-service-version>', // (optional)
80-
// reportUncaughtExceptions: false // (optional) Set to false to stop reporting unhandled exceptions.
81-
// reportUnhandledPromiseRejections: false // (optional) Set to false to stop reporting unhandled promise rejections.
82-
// disabled: true // (optional) Set to true to not report errors when calling report(), this can be used when developing locally.
83-
// context: {user: 'user1'} // (optional) You can set the user later using setUser()
84-
});
73+
```javascript
74+
// Warning: Experimental library, do not use in production environments.
75+
import StackdriverErrorReporter from 'stackdriver-errors-js';
76+
77+
const errorHandler = new StackdriverErrorReporter();
78+
errorHandler.start({
79+
key: myApiKey,
80+
projectId: myProjectId,
81+
82+
// The following optional arguments can also be provided:
83+
84+
// service: myServiceName,
85+
// Name of the service reporting the error, defaults to 'web'.
86+
87+
// version: myServiceVersion,
88+
// Version identifier of the service reporting the error.
89+
90+
// reportUncaughtExceptions: false
91+
// Set to false to prevent reporting unhandled exceptions.
92+
93+
// reportUnhandledPromiseRejections: false
94+
// Set to false to prevent reporting unhandled promise rejections.
95+
96+
// disabled: true
97+
// Set to true to not send error reports, this can be used when developing locally.
98+
99+
// context: {user: 'user1'}
100+
// You can set the user later using setUser()
85101
});
86-
</script>
87102
```
88103

89-
### Usage
104+
Note 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:
90105

91-
Unhandled exception will now automatically be reported to Stackdriver Error Reporting.
106+
```javascript
107+
var StackdriverErrorReporter = require('stackdriver-errors-js/dist/stackdriver-errors-concat.min.js');
92108

93-
You can also change your application code to report errors: `try { ... } catch(e) { errorHandler.report(e); }` or simply `errorHandler.report('Something broke!');`.
109+
var errorHandler = new StackdriverErrorReporter();
110+
errorHandler.start({
111+
key: myApiKey,
112+
projectId: myProjectId,
113+
// Other optional arguments can be supplied, see above.
114+
});
115+
```
94116

95-
You can set a user identifier at any time using `errorHandler.setUser('userId')`.
117+
### Usage
96118

97-
### Source maps
119+
Unhandled exception will now automatically be sent to Stackdriver Error Reporting.
98120

99-
Only publicly available JavaScript source maps are supported.
121+
You can also change your application code to report errors:
100122

101-
Your minified file need to be appended with a comment directive to your source map file:
102-
```JS
103-
//# sourceMappingURL=http://example.com/path/to/your/sourcemap.map
123+
```javascript
124+
try {
125+
...
126+
} catch(e) {
127+
errorHandler.report(e);
128+
}
129+
```
130+
131+
Or simply:
132+
133+
```javascript
134+
errorHandler.report('Something broke!');
104135
```
105136

137+
You can set a user identifier at any time using:
138+
139+
```javascript
140+
errorHandler.setUser('userId')
141+
```
106142

107143
## Setup for AngularJS
108144

109145
### Initialization
110146

111147
1. Load the `dist/stackdriver-errors-concat.min.js` JavaScript module.
112148

113-
2. Implement a new [exception handler](https://docs.angularjs.org/api/ng/service/$exceptionHandler) for your AngularJS application:
149+
2. Implement a new [AngularJS exception handler](https://docs.angularjs.org/api/ng/service/$exceptionHandler) for your application:
114150

115-
```JS
151+
```javascript
116152
angular.module('myAngularApp', [])
117153

118154
.factory('$exceptionHandler', ['$log', '$window', function($log, $window) {
119155
var StackdriverErrors = new $window.StackdriverErrorReporter();
120156
StackdriverErrors.start({
121157
key: '<my-api-key>',
122158
projectId: '<my-project-id>',
123-
service: '<my-service>', // (optional)
124-
version: '<my-service-version>' // (optional)
159+
// Other optional arguments can be supplied, see above.
125160
});
126161

127162
return function(exception, cause) {
@@ -135,13 +170,30 @@ angular.module('myAngularApp', [])
135170

136171
Uncaught exception in angular expressions will now be reported to Stackdriver Error Reporting.
137172

138-
If you wish, you can manually delegate exceptions, e.g. `try { ... } catch(e) { $exceptionHandler(e); }` or simply `$exceptionHandler('Something broke!');`.
173+
If you wish, you can manually delegate exceptions, for instance:
174+
```javascript
175+
try { ... } catch(e) { $exceptionHandler(e); }
176+
```
177+
Or simply:
178+
```javascript
179+
$exceptionHandler('Something broke!');
180+
```
139181

140182
## Setup for ReactJS
141183

142184
Follow the general instructions denoted in _Setup for JavaScript_ to load and initialize the library.
143185

144-
There 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`).
186+
There 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`).
187+
188+
## Source maps
189+
190+
Only publicly available JavaScript source maps are supported.
191+
192+
Your minified file need to be appended with a comment directive to your source map file:
193+
194+
```javascript
195+
//# sourceMappingURL=http://example.com/path/to/your/sourcemap.map
196+
```
145197

146198
## Configuring without an API key
147199

@@ -179,83 +231,71 @@ errorHandler.start({
179231

180232
### Only reporting in the production environment with Webpack
181233

182-
If 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:
234+
If 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:
183235

184236
```javascript
185237
// webpack.production.js
186-
// The rest of your webpack configuration
187-
// ...
188-
plugins: [
238+
239+
module.exports = {
240+
// ...
241+
plugins: [
189242
new webpack.DefinePlugin({
190243
'process.env.NODE_ENV': JSON.stringify('production')
191244
}),
192-
// Your other plugins
193-
]
194-
// ...
195-
// The rest of your webpack configuration
245+
],
246+
// ...
247+
}
196248
```
197249

198250
```javascript
199251
// index.js
200-
const environment = process.env.NODE_ENV;
201252

202-
if (environment === 'production') {
253+
if (process.env.NODE_ENV === 'production') {
203254
const errorHandler = new StackdriverErrorReporter();
204255
errorHandler.start({
205256
key: '<my-project-id>',
206257
projectId: '<my-project-id>',
207-
service: '<my-service>', // (optional)
208-
version: '<my-service-version>' // (optional)
209258
});
210259
}
211260
```
212261

213262
### Usage as a utility
214263

215-
If 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:
264+
If 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:
216265

217266
```javascript
218267
// errorHandlerUtility.js
219-
220-
const environment = process.env.NODE_ENV;
268+
import StackdriverErrorReporter from 'stackdriver-errors-js';
221269

222270
let errorHandler;
223271

224-
if (environment === 'production') {
225-
272+
if (process.env.NODE_ENV === 'production') {
226273
errorHandler = new StackdriverErrorReporter();
227274
errorHandler.start({
228275
key: '<my-project-id>',
229276
projectId: '<my-project-id>',
230-
service: '<my-service>', // (optional)
231-
version: '<my-service-version>' // (optional)
277+
// Other optional arguments can be supplied, see above.
232278
});
233-
234279
} else {
235280
errorHandler = {report: console.error};
236281
}
237282

238283
export default errorHandler;
239-
240284
```
241285

242-
Consumption of the errorHandlerUtility would essentially follow the following pattern:
286+
Consumption of `errorHandlerUtility` would essentially follow the following pattern:
243287

244288
```javascript
245-
// MyComponent.jsx
246289
import errorHandler from './errorHandlerUtility';
247290

248291
try {
249292
someFunctionThatThrows();
250293
} catch (error) {
251294
errorHandler.report(error);
252295
}
253-
254296
```
255297

256-
If the call to report has additional levels of wrapping code, extra
257-
frames can be trimmed from the top of generated stacks by using a
258-
number greater than one for the `skipLocalFrames` option:
298+
If 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:
259299

260300
```javascript
261301
import errorHandler from './errorHandlerUtility';
@@ -264,13 +304,23 @@ function backendReport (string) {
264304
// Skipping the two frames, for report() and for backendReport()
265305
errorHandler.report(error, {skipLocalFrames: 2});
266306
}
267-
268307
```
269308

270309
## FAQ
271310

272-
**Q: Should I use this code in my production application?** A: 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.
311+
**Q: Should I use this code in my production application?**
312+
A: 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.
313+
314+
**Q: Are private source maps supported?**
315+
A: No, see [issue #4](https://github.com/GoogleCloudPlatform/stackdriver-errors-js/issues/4).
316+
317+
**Q: Can I propose changes to the library?**
318+
A: Yes, see [the Contributing documentation](CONTRIBUTING.md) for more details.
273319

274-
**Q: Are private source maps supported?** A: No, see [#4](https://github.com/GoogleCloudPlatform/stackdriver-errors-js/issues/4)
275320

276-
**Q: Can I propose changes to the library?** A: Yes, see [the Contributing documentation](CONTRIBUTING.md) for more details.
321+
[travis-ci status image]: https://travis-ci.org/GoogleCloudPlatform/stackdriver-errors-js.svg?branch=master
322+
[travis-ci status link]: https://travis-ci.org/GoogleCloudPlatform/stackdriver-errors-js
323+
[david-dm status image]: https://david-dm.org/GoogleCloudPlatform/stackdriver-errors-js.svg
324+
[david-dm status link]: https://david-dm.org/GoogleCloudPlatform/stackdriver-errors-js
325+
[video thumbnail]: https://img.youtube.com/vi/cVpWVD75Hs8/0.jpg
326+
[video link]: https://www.youtube.com/watch?v=cVpWVD75Hs8

0 commit comments

Comments
 (0)