Skip to content

Commit 8d49298

Browse files
draffenspergerdraffensperger
committed
Trace logs correlation docs for logging-{winston,bunyan}
1 parent e1f075a commit 8d49298

4 files changed

Lines changed: 22 additions & 1 deletion

File tree

‎packages/logging-bunyan/README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ To format your request logs you can provide a `httpRequest` property on the buny
7979
![Request Log Example](doc/images/request-log.png)
8080

8181
```js
82-
logger.info({
82+
logger.info({
8383
httpRequest: {
8484
status: res.statusCode,
8585
requestUrl: req.url,
@@ -92,6 +92,13 @@ logger.info({
9292

9393
The `httpRequest` proprety must be a properly formatted [`HttpRequest`][http-request-message] message.
9494

95+
## Correlating Logs with Traces
96+
97+
If you use [@google-cloud/trace-agent][trace-agent] module, then this module will set the Stackdriver Logging [LogEntry][LogEntry] `trace` property based on the current trace context when available. That correlation allows you to [view log entries][trace-viewing-log-entries] inline with trace spans in the Stackdriver Trace Viewer. Example:
98+
99+
![Logs in Trace Example](/packages/logging-bunyan/doc/images/bunyan-logs-in-trace.png)
100+
101+
If you wish to set the Stackdriver LogEntry `trace` property with a custom value, then write a Bunyan log entry property for `'logging.googleapis.com/trace'`, which is exported by this module as `LOGGING_TRACE_KEY`.
95102

96103
[bunyan]: https://github.com/trentm/node-bunyan
97104
[@google-cloud/logging]: https://www.npmjs.com/package/@google-cloud/logging
@@ -102,3 +109,6 @@ The `httpRequest` proprety must be a properly formatted [`HttpRequest`][http-req
102109
[@google-cloud/error-reporting]: https://www.npmjs.com/package/@google-cloud/error-reporting
103110
[uncaught]: https://nodejs.org/api/process.html#process_event_uncaughtexception
104111
[unhandled]: https://nodejs.org/api/process.html#process_event_unhandledrejection
112+
[trace-agent]: https://www.npmjs.com/package/@google-cloud/trace-agent
113+
[LogEntry]: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry
114+
[trace-viewing-log-entries]: https://cloud.google.com/trace/docs/viewing-details#log_entries

‎packages/logging-bunyan/doc/images/bunyan-logs-in-trace.png‎

23.9 KB
Loading

‎packages/logging-winston/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,14 @@ winston.info(`${req.url} endpoint hit`, {
9696

9797
The `httpRequest` proprety must be a properly formatted [`HttpRequest`][http-request-message] message.
9898

99+
## Correlating Logs with Traces
100+
101+
If you use [@google-cloud/trace-agent][trace-agent] module, then this module will set the Stackdriver Logging [LogEntry][LogEntry] `trace` property based on the current trace context when available. That correlation allows you to [view log entries][trace-viewing-log-entries] inline with trace spans in the Stackdriver Trace Viewer. Example:
102+
103+
![Logs in Trace Example](/packages/logging-winston/doc/images/winston-logs-in-trace.png)
104+
105+
If you wish to set the LogEntry `trace` property with a custom value, then set a winston metadata property for `'logging.googleapis.com/trace'`, which is exported by this module as `LOGGING_TRACE_KEY`.
106+
99107
[winston]: https://github.com/winstonjs/winston
100108
[@google-cloud/logging]: https://www.npmjs.com/package/@google-cloud/logging
101109
[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
@@ -105,3 +113,6 @@ The `httpRequest` proprety must be a properly formatted [`HttpRequest`][http-req
105113
[@google-cloud/error-reporting]: https://www.npmjs.com/package/@google-cloud/error-reporting
106114
[uncaught]: https://nodejs.org/api/process.html#process_event_uncaughtexception
107115
[unhandled]: https://nodejs.org/api/process.html#process_event_unhandledrejection
116+
[trace-agent]: https://www.npmjs.com/package/@google-cloud/trace-agent
117+
[LogEntry]: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry
118+
[trace-viewing-log-entries]: https://cloud.google.com/trace/docs/viewing-details#log_entries

‎packages/logging-winston/doc/images/winston-logs-in-trace.png‎

22 KB
Loading

0 commit comments

Comments
 (0)