logging-winston: HttpRequest support

If the winston provided metadata includes a httpRequest property,
format that as the HttpRequest message. This allows Stackdriver logging
to format request logs nicely.

Ref: #2325

packages/logging-winston/README.md

@@ -70,7 +70,28 @@ winston.add(transport, {
 // ...you're good to go!
 ```
 
+## 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:
+
++![Request Log Example](/doc/images/request-log.png)
+
+```js
+winston.info(`${req.url} endpoint hit`, {
+  httpRequest: {
+    status: res.statusCode,
+    requestUrl: req.url,
+    requestMethod: req.method,
+    remoteIp: req.connection.remoteAddress,
+    // etc.
+  }
+});
+```
+
+The `httpRequest` proprety must be a properly formatted [`HttpRequest`][http-request-message] message.
+
 [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
 [dev-console]: https://console.developers.google.com/project
+[http-request-message]: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#HttpRequest

packages/logging-winston/src/index.js

@@ -142,8 +142,10 @@ util.inherits(LoggingWinston, winston.Transport);
  *     appropriate Stackdriver logging severity level.
  * @param {string} msg - The message to be logged.
  * @param {object=} metadata - Winston-provided metadata that should be attached
- *     to the log entry. Each property will be converted to a string using
- *     `util.inspect`.
+ *     to the log entry. If a `httpRequest` property is set, it will be treated
+ *     as a [HttpRequest]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#HttpRequest}
+ *     request log message. If `options.inspectMetadata` is set, we will convert
+ *     the remaining properties to `string`s before reporting.
  * @param {function=} callback - A callback that is invoked when the logging
  *     agent either succeeds or gives up writing the log entry to the remote
  *     server.
@@ -191,6 +193,17 @@ LoggingWinston.prototype.log = function(levelName, msg, metadata, callback) {
   if (is.object(metadata)) {
     data.metadata =
       this.inspectMetadata_ ? mapValues(metadata, util.inspect) : metadata;
+
+    // If the metadata contains a httpRequest property, promote it to the entry
+    // metadata. This allows Stackdriver to use request log formatting.
+    // https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#HttpRequest
+    // Note that the httpRequest field must properly validate as HttpRequest
+    // proto message, or the log entry would be rejected by the API. We no do
+    // validation here.
+    if (metadata.httpRequest) {
+      entryMetadata.httpRequest = metadata.httpRequest;
+      delete data.metadata.httpRequest;
+    }
   }
 
   var entry = this.log_.entry(entryMetadata, data);

packages/logging-winston/test/index.js

@@ -273,6 +273,28 @@ describe('logging-winston', function() {
       loggingWinston.log(LEVEL, MESSAGE, METADATA, assert.ifError);
     });
 
+    it('should promote httpRequest property to metadata', function(done) {
+      var HTTP_REQUEST = {
+        statusCode: 418
+      };
+      const metadataWithRequest = extend({
+        httpRequest: HTTP_REQUEST
+      }, METADATA);
+
+      loggingWinston.log_.entry = function(entryMetadata, data) {
+        assert.deepStrictEqual(entryMetadata, {
+          resource: loggingWinston.resource_,
+          httpRequest: HTTP_REQUEST
+        });
+        assert.deepStrictEqual(data, {
+          message: MESSAGE,
+          metadata: METADATA
+        });
+        done();
+      };
+      loggingWinston.log(LEVEL, MESSAGE, metadataWithRequest, assert.ifError);
+    });
+
     it('should write to the log', function(done) {
       var entry = {};