@google-cloud/logging-winston - npm Package Compare versions

Comparing version 4.1.3 to 4.2.0

build/src/common.d.ts

@@ -1,3 +0,5 @@
-import { protos, ServiceContext, Log } from '@google-cloud/logging';
+import { protos, ServiceContext } from '@google-cloud/logging';
+import { LogSeverityFunctions } from '@google-cloud/logging/build/src/utils/log-common';
 import { Options } from '.';
+import { Entry, LogEntry } from '@google-cloud/logging/build/src/entry';
 declare type Callback = (err: Error | null, apiResponse?: {}) => void;
@@ -38,3 +40,3 @@ export declare type MonitoredResource = protos.google.api.MonitoredResource;
     private levels;
-    stackdriverLog: Log;
+    cloudLog: LogSeverityFunctions;
     private resource;
@@ -45,2 +47,3 @@ private serviceContext;
     private defaultCallback?;
+    redirectToStdout: boolean;
     static readonly LOGGING_TRACE_KEY = "logging.googleapis.com/trace";
@@ -50,2 +53,3 @@ static readonly LOGGING_SPAN_KEY = "logging.googleapis.com/spanId";
     log(level: string, message: string, metadata: MetadataArg | undefined, callback: Callback): void;
+    entry(metadata?: LogEntry, data?: string | {}): Entry;
 }
@@ -52,0 +56,0 @@ declare type MetadataArg = {

build/src/common.js

@@ -20,3 +20,3 @@ "use strict";
 const mapValues = require("lodash.mapvalues");
-// Map of npm output levels to Stackdriver Logging levels.
+// Map of npm output levels to Cloud Logging levels.
 const NPM_LEVEL_NAME_TO_CODE = {
@@ -30,4 +30,4 @@ error: 3,
 };
-// Map of Stackdriver Logging levels.
-const STACKDRIVER_LOGGING_LEVEL_CODE_TO_NAME = {
+// Map of Cloud Logging levels.
+const CLOUD_LOGGING_LEVEL_CODE_TO_NAME = {
     0: 'emergency',
@@ -78,2 +78,3 @@ 1: 'alert',
     constructor(options) {
+        var _a;
         options = Object.assign({
@@ -85,9 +86,15 @@ scopes: ['https://www.googleapis.com/auth/logging.write'],
         this.levels = options.levels || NPM_LEVEL_NAME_TO_CODE;
-        this.stackdriverLog = new logging_1.Logging(options).log(this.logName, {
-            removeCircular: true,
-            // See: https://cloud.google.com/logging/quotas, a log size of
-            // 250,000 has been chosen to keep us comfortably within the
-            // 256,000 limit.
-            maxEntrySize: options.maxEntrySize || 250000,
-        });
+        this.redirectToStdout = (_a = options.redirectToStdout) !== null && _a !== void 0 ? _a : false;
+        if (!this.redirectToStdout) {
+            this.cloudLog = new logging_1.Logging(options).log(this.logName, {
+                removeCircular: true,
+                // See: https://cloud.google.com/logging/quotas, a log size of
+                // 250,000 has been chosen to keep us comfortably within the
+                // 256,000 limit.
+                maxEntrySize: options.maxEntrySize || 250000,
+            });
+        }
+        else {
+            this.cloudLog = new logging_1.Logging(options).logSync(this.logName);
+        }
         this.resource = options.resource;
@@ -100,3 +107,2 @@ this.serviceContext = options.serviceContext;
     log(level, message, metadata, callback) {
-        var _a;
         metadata = metadata || {};
@@ -109,9 +115,9 @@ message = message || '';
         const levelCode = this.levels[level];
-        const stackdriverLevel = STACKDRIVER_LOGGING_LEVEL_CODE_TO_NAME[levelCode];
+        const cloudLevel = CLOUD_LOGGING_LEVEL_CODE_TO_NAME[levelCode];
         const data = {};
-        // Stackdriver Logs Viewer picks up the summary line from the `message`
+        // Cloud Logs Viewer picks up the summary line from the `message`
         // property of the jsonPayload.
         // https://cloud.google.com/logging/docs/view/logs_viewer_v2#expanding.
         //
-        // For error messages at severity 'error' and higher, Stackdriver
+        // For error messages at severity 'error' and higher,
         // Error Reporting will pick up error messages if the full stack trace is
@@ -139,3 +145,3 @@ // included in the textPayload or the message property of the jsonPayload.
         // If the metadata contains a httpRequest property, promote it to the
-        // entry metadata. This allows Stackdriver to use request log formatting.
+        // entry metadata. This allows Cloud Logging to use request log formatting.
         // https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#HttpRequest
@@ -190,5 +196,27 @@ // Note that the httpRequest field must properly validate as HttpRequest
         }
-        const entry = this.stackdriverLog.entry(entryMetadata, data);
-        this.stackdriverLog[stackdriverLevel](entry, (_a = this.defaultCallback) !== null && _a !== void 0 ? _a : callback);
+        const entry = this.entry(entryMetadata, data);
+        // Make sure that both callbacks are called in case if provided
+        const newCallback = (err, apiResponse) => {
+            if (callback) {
+                callback(err, apiResponse);
+            }
+            if (this.defaultCallback) {
+                this.defaultCallback(err, apiResponse);
+            }
+        };
+        this.cloudLog[cloudLevel](entry, newCallback);
+        // The LogSync class does not supports callback. However Writable class always
+        // provides onwrite() callback which needs to be called after each log is written,
+        // so the stream would remove writing state. Since this.defaultCallback can also be set, we
+        // should call it explicitly as well.
+        if (this.redirectToStdout) {
+            newCallback(null, undefined);
+        }
     }
+    entry(metadata, data) {
+        if (this.redirectToStdout) {
+            return this.cloudLog.entry(metadata, data);
+        }
+        return this.cloudLog.entry(metadata, data);
+    }
 }
@@ -195,0 +223,0 @@ exports.LoggingCommon = LoggingCommon;

build/src/index.d.ts

@@ -57,2 +57,9 @@ import TransportStream = require('winston-transport');
     defaultCallback?: Callback;
+    /**
+     * Boolen flag that opts-in redirecting the output to STDOUT instead of ingesting logs to Cloud
+     * Logging using Logging API. Defaults to {@code false}. Redirecting logs can be used in
+     * Google Cloud environments with installed logging agent to delegate log ingestions to the
+     * agent. Redirected logs are formatted as one line Json string following the structured logging guidelines.
+     */
+    redirectToStdout?: boolean;
 }
@@ -59,0 +66,0 @@ /**

build/src/middleware/express.js

@@ -41,3 +41,5 @@ "use strict";
     }
-    const auth = transport.common.stackdriverLog.logging.auth;
+    const auth = (transport.common.redirectToStdout
+        ? transport.common.cloudLog
+        : transport.common.cloudLog).logging.auth;
     const [env, projectId] = await Promise.all([
@@ -44,0 +46,0 @@ auth.getEnv(),

CHANGELOG.md

@@ -7,2 +7,9 @@ # Changelog
 
+## [4.2.0](https://github.com/googleapis/nodejs-logging-winston/compare/v4.1.3...v4.2.0) (2022-03-18)
+
+
+### Features
+
+* Add support to print structured logging to STDOUT ([#676](https://github.com/googleapis/nodejs-logging-winston/issues/676)) ([76135ca](https://github.com/googleapis/nodejs-logging-winston/commit/76135ca81cf0a2e6e48bc34e4b982daa64ce2cd9))
+
 ### [4.1.3](https://github.com/googleapis/nodejs-logging-winston/compare/v4.1.2...v4.1.3) (2022-03-09)
@@ -9,0 +16,0 @@

package.json

 {
   "name": "@google-cloud/logging-winston",
   "description": "Stackdriver Logging transport for Winston",
-  "version": "4.1.3",
+  "version": "4.2.0",
   "license": "Apache-2.0",
@@ -6,0 +6,0 @@ "author": "Google Inc.",

README.md

@@ -161,3 +161,3 @@ [//]: # "This README.md file is auto-generated, all changes to this file will be lost."
 
-Any `Error` objects you log at severity `error` or higher can automatically be picked up by [Stackdriver Error Reporting](https://cloud.google.com/error-reporting/) if you have specified a `serviceContext.service` when instantiating a `LoggingWinston` instance:
+Any `Error` objects you log at severity `error` or higher can automatically be picked up by [Error Reporting](https://cloud.google.com/error-reporting/) if you have specified a `serviceContext.service` when instantiating a `LoggingWinston` instance:
 
@@ -168,3 +168,3 @@ ```javascript
     service: 'my-service', // required to report logged errors
-                        // to the Google Cloud Error Reporting
+                        // to the Error Reporting
                         // console
@@ -184,3 +184,3 @@ version: 'my-version'
 
-The `LoggingWinston` class creates an instance of `LoggingCommon` which uses the `Log` class from `@google-cloud/logging` package to write log entries. 
+The `LoggingWinston` class creates an instance of `LoggingCommon` which by default uses the `Log` class from `@google-cloud/logging` package to write log entries. 
 The `Log` class writes logs asynchronously and there are cases when log entries cannot be written and an error is 
@@ -295,3 +295,25 @@ thrown - if error is not handled properly, it could crash the application. One possible way to handle the error is to provide a default callback
 
+### Alternative way to ingest logs in Google Cloud managed environments
+If you use this library with the Cloud Logging Agent, you can configure the handler to output logs to `process.stdout` using
+the [structured logging Json format](https://cloud.google.com/logging/docs/structured-logging#special-payload-fields).
+To do this, add `redirectToStdout: true` parameter to the `LoggingWinston` constructor as in sample below.
+You can use this parameter when running applications in Google Cloud managed environments such as AppEngine, Cloud Run,
+Cloud Function or GKE. The logger agent installed on these environments can capture `process.stdout` and ingest it into Cloud Logging.
+The agent can parse structured logs printed to `process.stdout` and capture additional log metadata beside the log payload.
+It is recommended to set `redirectToStdout: true` in serverless environments like Cloud Functions since it could 
+decrease logging record loss upon execution termination - since all logs are written to `process.stdout` those
+would be picked up by the Cloud Logging Agent running in Google Cloud managed environment. 
 
+```js
+// Imports the Google Cloud client library for Winston
+const {LoggingWinston} = require('@google-cloud/logging-winston');
+
+// Creates a client that writes logs to stdout
+const loggingWinston = new LoggingWinston({
+  projectId: 'your-project-id',
+  keyFilename: '/path/to/key.json',
+  redirectToStdout: true,
+});
+
+
 ## Samples
@@ -298,0 +320,0 @@

No alert changes

Improved metrics

Total package byte prevSize

103357

increased by3.66%

Lines of code

778

increased by5.56%

Number of lines in readme file

393

increased by5.93%

No dependency changes