Trace logs correlation docs for logging-{winston,bunyan} (#2630)

README.md

@@ -96,6 +96,25 @@ winston.info(`${req.url} endpoint hit`, {
 
 The `httpRequest` proprety must be a properly formatted [`HttpRequest`][http-request-message] message.
 
+## Correlating Logs with Traces
+
+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:
+
+![Logs in Trace Example](/packages/logging-winston/doc/images/winston-logs-in-trace.png)
+
+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`. For example:
+
+```js
+const winston = require('winston');
+const transport = require('@google-cloud/logging-winston');
+
+...
+
+winston.info('Log entry with custom trace value', {
+  [transport.LOGGING_TRACE_KEY]: 'custom-trace-value'
+});
+```
+
 [winston]: https://github.com/winstonjs/winston
 [@google-cloud/logging]: https://www.npmjs.com/package/@google-cloud/logging
 [gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
@@ -105,3 +124,6 @@ The `httpRequest` proprety must be a properly formatted [`HttpRequest`][http-req
 [@google-cloud/error-reporting]: https://www.npmjs.com/package/@google-cloud/error-reporting
 [uncaught]: https://nodejs.org/api/process.html#process_event_uncaughtexception
 [unhandled]: https://nodejs.org/api/process.html#process_event_unhandledrejection
+[trace-agent]: https://www.npmjs.com/package/@google-cloud/trace-agent
+[LogEntry]: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry
+[trace-viewing-log-entries]: https://cloud.google.com/trace/docs/viewing-details#log_entries