From 9de91cd3f7bf6c5923a78a88ba4f00c92ba200dc Mon Sep 17 00:00:00 2001 From: Ali Ijaz Sheikh Date: Fri, 26 May 2017 00:17:32 -0700 Subject: [PATCH 1/2] Doc error-reporting integration with logs Document loggin-{winston,bunyan} and error-reporting from each other's README files. --- packages/error-reporting/README.md | 21 ++++++++++++++++++--- packages/logging-bunyan/README.md | 6 ++++++ packages/logging-winston/README.md | 6 ++++++ 3 files changed, 30 insertions(+), 3 deletions(-) diff --git a/packages/error-reporting/README.md b/packages/error-reporting/README.md index 91e2ac259b8..f80430e51b6 100644 --- a/packages/error-reporting/README.md +++ b/packages/error-reporting/README.md @@ -9,7 +9,7 @@ This module provides Stackdriver Error Reporting support for Node.js 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. +applications running in almost any environment. ![Stackdriver Error Reporting overview](doc/images/errors-overview.png) @@ -17,6 +17,13 @@ Here's an introductory video that provides some more details: [![Learn about Error Reporting in Stackdriver](https://img.youtube.com/vi/cVpWVD75Hs8/0.jpg)](https://www.youtube.com/watch?v=cVpWVD75Hs8) +Note that [@google-cloud/logging-winston][logging-winston] and +[@google-cloud/logging-bunyan][logging-bunyan] automatically integrate with the +Error Reporting service for Error objects logged at severity `error` or higher, +for applications running on Google Cloud Platform. If you are already using +Winston or Bunyan in your application, and don't need direct access/control of +error reporting, you may want to check those modules as well. + ## Prerequisites 1. Your application needs to use Node.js version 4.x or greater. @@ -48,6 +55,9 @@ var errors = require('@google-cloud/error-reporting')({ // Report an error to the Stackdriver Error Reporting API errors.report(new Error('Something broke!')); + +// We also provide error handling middleware for express, hapi, restify & koa. +// See sections below. ``` 3. **View reported errors:** @@ -184,6 +194,8 @@ 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); @@ -253,10 +265,13 @@ server.head('/hello/:name', respond); server.listen(3000); ``` -[gcloud-sdk]: https://cloud.google.com/sdk/gcloud/ [app-default-credentials]: https://developers.google.com/identity/protocols/application-default-credentials -[service-account]: https://console.developers.google.com/apis/credentials/serviceaccountkey +[express-error-docs]: https://expressjs.com/en/guide/error-handling.html +[gcloud-sdk]: https://cloud.google.com/sdk/gcloud/ +[logging-bunyan]: https://www.npmjs.com/package/@google-cloud/logging-bunyan +[logging-winston]: https://www.npmjs.com/package/@google-cloud/logging-winston [npm-image]: https://badge.fury.io/js/%40google-cloud%2Ferror-reporting.svg [npm-url]: https://npmjs.org/package/@google-cloud/error-reporting +[service-account]: https://console.developers.google.com/apis/credentials/serviceaccountkey [snyk-image]: https://snyk.io/test/npm/@google-cloud/error-reporting/badge.svg [snyk-url]: https://snyk.io/test/npm/@google-cloud/error-reporting diff --git a/packages/logging-bunyan/README.md b/packages/logging-bunyan/README.md index 1408be53948..ed2700e73d5 100644 --- a/packages/logging-bunyan/README.md +++ b/packages/logging-bunyan/README.md @@ -66,6 +66,10 @@ var loggingBunyan = require('@google-cloud/logging-bunyan')({ // ...you're good to go! ``` +## Error Reporting + +Any `Error` objects you log at severity `error` at higher can automatically be picked up by [Stackdriver Error Reporting][error-reporting] if your application is running on Google Cloud Platform. You may also want to see [@google-cloud/error-reporting][@google-cloud/error-reporting] module which provides direct access to the Error Reporting API. + ## Formatting Request Logs To format your request logs you can provide a `httpRequest` property on the bunyan metadata you provide along with the log message. We will treat this as the [`HttpRequest`][http-request-message] message and Stackdriver logging will show this as a request log. Example: @@ -92,3 +96,5 @@ The `httpRequest` proprety must be a properly formatted [`HttpRequest`][http-req [gce-how-to]: https://cloud.google.com/compute/docs/authentication#using [http-request-message]: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#HttpRequest [dev-console]: https://console.developers.google.com/project +[error-reporting]: https://cloud.google.com/error-reporting/ +[@google-cloud/error-reporting]: https://www.npmjs.com/package/@google-cloud/error-reporting diff --git a/packages/logging-winston/README.md b/packages/logging-winston/README.md index 54376ce18a4..cd21091e5fc 100644 --- a/packages/logging-winston/README.md +++ b/packages/logging-winston/README.md @@ -70,6 +70,10 @@ winston.add(transport, { // ...you're good to go! ``` +## Error Reporting + +Any `Error` objects you log at severity `error` at higher can automatically be picked up by [Stackdriver Error Reporting][error-reporting] if your application is running on Google Cloud Platform. You may also want to see [@google-cloud/error-reporting][@google-cloud/error-reporting] module which provides direct access to the Error Reporting API. + ## Formatting Request Logs To format your request logs you can provide a `httpRequest` property as part of the log metadata you provide to winston. We will treat this as the [`HttpRequest`][http-request-message] message and Stackdriver logging will show this as a request log. Example: @@ -95,3 +99,5 @@ The `httpRequest` proprety must be a properly formatted [`HttpRequest`][http-req [gce-how-to]: https://cloud.google.com/compute/docs/authentication#using [dev-console]: https://console.developers.google.com/project [http-request-message]: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#HttpRequest +[error-reporting]: https://cloud.google.com/error-reporting/ +[@google-cloud/error-reporting]: https://www.npmjs.com/package/@google-cloud/error-reporting From 3ad35ae87cf4cfa434e1cfefbfd4f7aade78b8e3 Mon Sep 17 00:00:00 2001 From: Ali Ijaz Sheikh Date: Tue, 30 May 2017 17:03:05 -0700 Subject: [PATCH 2/2] Fix code review comments --- packages/logging-bunyan/README.md | 2 +- packages/logging-winston/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/logging-bunyan/README.md b/packages/logging-bunyan/README.md index ed2700e73d5..0439f6d9543 100644 --- a/packages/logging-bunyan/README.md +++ b/packages/logging-bunyan/README.md @@ -68,7 +68,7 @@ var loggingBunyan = require('@google-cloud/logging-bunyan')({ ## Error Reporting -Any `Error` objects you log at severity `error` at higher can automatically be picked up by [Stackdriver Error Reporting][error-reporting] if your application is running on Google Cloud Platform. You may also want to see [@google-cloud/error-reporting][@google-cloud/error-reporting] module which provides direct access to the Error Reporting API. +Any `Error` objects you log at severity `error` or higher can automatically be picked up by [Stackdriver Error Reporting][error-reporting] if your application is running on Google Cloud Platform. You may also want to see the [@google-cloud/error-reporting][@google-cloud/error-reporting] module which provides direct access to the Error Reporting API. ## Formatting Request Logs diff --git a/packages/logging-winston/README.md b/packages/logging-winston/README.md index cd21091e5fc..21949cd1c08 100644 --- a/packages/logging-winston/README.md +++ b/packages/logging-winston/README.md @@ -72,7 +72,7 @@ winston.add(transport, { ## Error Reporting -Any `Error` objects you log at severity `error` at higher can automatically be picked up by [Stackdriver Error Reporting][error-reporting] if your application is running on Google Cloud Platform. You may also want to see [@google-cloud/error-reporting][@google-cloud/error-reporting] module which provides direct access to the Error Reporting API. +Any `Error` objects you log at severity `error` or higher can automatically be picked up by [Stackdriver Error Reporting][error-reporting] if your application is running on Google Cloud Platform. You may also want to see the [@google-cloud/error-reporting][@google-cloud/error-reporting] module which provides direct access to the Error Reporting API. ## Formatting Request Logs