fix(logging-utils): export LogSeverity as value and treat 'true' as '*' alias (#9718)

Exports `LogSeverity` as a runtime value and treats `"true"` as `"*"`

### Changes:
- Export `LogSeverity` as a value instead of `export type` in
`src/index.ts`
- Normalize `nodeFlag === 'true'` to `'*'` in `DebugLogBackendBase`
- Added unit tests for runtime `LogSeverity` exports and `"true"` filter
normalization.

Author: shivanee-p

core/packages/logging-utils/README.md

@@ -6,9 +6,8 @@ This package defines an ad-hoc debug logger utility that can be used as a lightw
 ## Contracts
 These are logging utilities meant primarily for use as an "adhoc debug logger" inside Google libraries. It's possible to use this outside of that context, but it is currently not supported. (You're on your own.)
 
-Additionally, everything about the debug logging is not intended to be a stable interface - you can't rely on messages to remain the same, or to continue to exist from one version to the next. For now, it is meant to be a tool for local usage by users, to get the equivalent of "printf debugging" output. In the future, it may tie into more things (OpenTelemetry Logging, etc). Structured log output is possible for vacuuming into Cloud Logging.
-
-This npm package itself is intended to follow semver standards for its own interfaces, but no guarantees are made for supported time windows, etc.
+* **Stable Package API (SemVer 1.x):** The exported programmatic interface—`log()`, `placeholder`, `LogFields`, `LogSeverity`, `AdhocDebugLogFunction` (including `.on('log', ...)` and `.sublog()`), `setBackend()`, `getNodeBackend()`, `getStructuredBackend()`, and `env.nodeEnables` (`GOOGLE_SDK_NODE_LOGGING`)—is a strict SemVer-stable contract used across `google-gax`, `google-auth-library`, `gcp-metadata`, and `@google-cloud/*`.
+* **Non-Contractual Log Output:** Exact human-readable log message strings and the addition of new diagnostic attributes in `LogFields.other` may evolve across minor versions so customers do not rely on regex-parsing prose messages. For now, it is meant to be a tool for local usage by users, to get the equivalent of "printf debugging" output. In the future, it may tie into more things (OpenTelemetry Logging, etc). Structured log output is possible for vacuuming into Cloud Logging.
 
 ## Usage
 The user interface for this logging is very similar to Node's built-in logging. The primary unit of logging is called a "system", and some libraries may have sub-units called "subsystems". You separate the system and subsystem with a colon, like "pubsub:leasing" or similar. Wildcards may be used (e.g. "pubsub:*"), and multiple of these system/system:subsystem pairs may be listed out, separated by commas. For generated GAPIC libraries, the "system" will generally be the part of the package name specific to the library (e.g. `@google-cloud/translate` will be `translate`).

core/packages/logging-utils/src/index.ts

@@ -14,9 +14,5 @@
 
 export * from './logging-utils';
 // 🌟 ADDED EXPORT FOR TYPES 🌟
-export type {
-  LogFields,
-  LogSeverity,
-  AdhocDebugLogFunction,
-  DebugLogBackend,
-} from './types';
+export {LogSeverity} from './types';
+export type {LogFields, AdhocDebugLogFunction, DebugLogBackend} from './types';

core/packages/logging-utils/src/logging-utils.ts

@@ -123,7 +123,7 @@ export abstract class DebugLogBackendBase implements DebugLogBackend {
     // Look for the Node config variable for what systems to enable. We'll store
     // these for the log method below, which will call setFilters() once.
     let nodeFlag = process.env[env.nodeEnables] ?? '*';
-    if (nodeFlag === 'all') {
+    if (nodeFlag === 'all' || nodeFlag === 'true') {
       nodeFlag = '*';
     }
     this.filters = nodeFlag.split(',');

core/packages/logging-utils/test/logging-utils.ts

@@ -16,20 +16,19 @@ import {describe, it} from 'mocha';
 import * as assert from 'assert';
 import * as sinon from 'sinon';
 
-import * as al from '../src/logging-utils';
-import * as alTypes from '../src/types';
+import * as al from '../src/index';
 
 interface TestLog {
   namespace: string;
-  fields: alTypes.LogFields;
+  fields: al.LogFields;
   args: unknown[];
 }
 
 class TestSink extends al.DebugLogBackendBase {
   logs: TestLog[] = [];
 
   makeLogger(namespace: string): any {
-    return (fields: alTypes.LogFields, ...args: unknown[]) => {
+    return (fields: al.LogFields, ...args: unknown[]) => {
       this.logs.push({namespace, fields, args});
     };
   }
@@ -57,13 +56,29 @@ describe('adhoc-logging', () => {
     });
 
     it('obeys "all" as an alias for "*"', () => {
-      al.setBackend(sink);
-      sink.reset();
-
       process.env[al.env.nodeEnables] = 'all';
+      const backend = new TestSink();
+      al.setBackend(backend);
+      assert.deepStrictEqual(backend.filters, ['*']);
       const logger = al.log(system);
       logger({}, 'foo');
-      assert.deepStrictEqual(sink.logs, [
+      assert.deepStrictEqual(backend.logs, [
+        {
+          namespace: system,
+          fields: {},
+          args: ['foo'],
+        },
+      ]);
+    });
+
+    it('obeys "true" as an alias for "*"', () => {
+      process.env[al.env.nodeEnables] = 'true';
+      const backend = new TestSink();
+      al.setBackend(backend);
+      assert.deepStrictEqual(backend.filters, ['*']);
+      const logger = al.log(system);
+      logger({}, 'foo');
+      assert.deepStrictEqual(backend.logs, [
         {
           namespace: system,
           fields: {},
@@ -121,13 +136,13 @@ describe('adhoc-logging', () => {
     });
 
     it('logs with fields', () => {
-      logger({severity: alTypes.LogSeverity.INFO}, 'test log', 5, {
+      logger({severity: al.LogSeverity.INFO}, 'test log', 5, {
         other: 'foo',
       });
       assert.deepStrictEqual(sink.logs, [
         {
           namespace: system,
-          fields: {severity: alTypes.LogSeverity.INFO},
+          fields: {severity: al.LogSeverity.INFO},
           args: ['test log', 5, {other: 'foo'}],
         },
       ]);
@@ -141,22 +156,22 @@ describe('adhoc-logging', () => {
       assert.deepStrictEqual(sink.logs, [
         {
           namespace: system,
-          fields: {severity: alTypes.LogSeverity.INFO},
+          fields: {severity: al.LogSeverity.INFO},
           args: ['test info'],
         },
         {
           namespace: system,
-          fields: {severity: alTypes.LogSeverity.WARNING},
+          fields: {severity: al.LogSeverity.WARNING},
           args: ['test warn'],
         },
         {
           namespace: system,
-          fields: {severity: alTypes.LogSeverity.DEBUG},
+          fields: {severity: al.LogSeverity.DEBUG},
           args: ['test debug'],
         },
         {
           namespace: system,
-          fields: {severity: alTypes.LogSeverity.ERROR},
+          fields: {severity: al.LogSeverity.ERROR},
           args: ['test error'],
         },
       ]);
@@ -190,13 +205,13 @@ describe('adhoc-logging', () => {
     it('allows receiving logs', () => {
       const received = [{fields: {}, args: [] as unknown[]}];
       received.pop();
-      logger.on('log', (fields: alTypes.LogFields, args: unknown[]) => {
+      logger.on('log', (fields: al.LogFields, args: unknown[]) => {
         received.push({fields, args});
       });
       logger.info('cool cool');
       assert.deepStrictEqual(received, [
         {
-          fields: {severity: alTypes.LogSeverity.INFO},
+          fields: {severity: al.LogSeverity.INFO},
           args: ['cool cool'],
         },
       ]);
@@ -297,4 +312,90 @@ describe('adhoc-logging', () => {
       ]);
     });
   });
+
+  describe('Public entrypoint contract (src/index.ts)', () => {
+    it('exports LogSeverity as a runtime enum from index', () => {
+      assert.strictEqual(al.LogSeverity.DEFAULT, 'DEFAULT');
+      assert.strictEqual(al.LogSeverity.DEBUG, 'DEBUG');
+      assert.strictEqual(al.LogSeverity.INFO, 'INFO');
+      assert.strictEqual(al.LogSeverity.WARNING, 'WARNING');
+      assert.strictEqual(al.LogSeverity.ERROR, 'ERROR');
+    });
+
+    it('exports required functions, classes, and constants on the public entrypoint', () => {
+      assert.strictEqual(typeof al.log, 'function');
+      assert.strictEqual(typeof al.placeholder, 'function');
+      assert.strictEqual(typeof al.setBackend, 'function');
+      assert.strictEqual(typeof al.getNodeBackend, 'function');
+      assert.strictEqual(typeof al.getDebugBackend, 'function');
+      assert.strictEqual(typeof al.getStructuredBackend, 'function');
+      assert.strictEqual(typeof al.AdhocDebugLogger, 'function');
+      assert.strictEqual(typeof al.DebugLogBackendBase, 'function');
+      assert.strictEqual(typeof al.env, 'object');
+      assert.strictEqual(al.env.nodeEnables, 'GOOGLE_SDK_NODE_LOGGING');
+    });
+
+    it('exports placeholder conforming to AdhocDebugLogFunction contract', () => {
+      const fn: al.AdhocDebugLogFunction = al.placeholder;
+      assert.strictEqual(typeof fn.debug, 'function');
+      assert.strictEqual(typeof fn.info, 'function');
+      assert.strictEqual(typeof fn.warn, 'function');
+      assert.strictEqual(typeof fn.error, 'function');
+      assert.strictEqual(typeof fn.sublog, 'function');
+      assert.strictEqual(typeof fn.on, 'function');
+      assert.ok(fn.instance instanceof al.AdhocDebugLogger);
+
+      // Invoking placeholder methods when disabled is a safe no-op.
+      al.setBackend(null);
+      assert.doesNotThrow(() => {
+        fn({severity: al.LogSeverity.DEBUG, other: {key: 'val'}}, 'noop');
+        fn.debug('noop');
+        fn.info('noop');
+        fn.warn('noop');
+        fn.error('noop');
+        assert.strictEqual(fn.sublog('child'), al.placeholder);
+      });
+    });
+
+    it('preserves AdhocDebugLogFunction, LogFields, and DebugLogBackend contracts via log()', () => {
+      al.setBackend(sink);
+      sink.reset();
+      process.env[al.env.nodeEnables] = '*';
+
+      const logger: al.AdhocDebugLogFunction = al.log('contract-system');
+      assert.strictEqual(typeof logger, 'function');
+      assert.strictEqual(typeof logger.debug, 'function');
+      assert.strictEqual(typeof logger.info, 'function');
+      assert.strictEqual(typeof logger.warn, 'function');
+      assert.strictEqual(typeof logger.error, 'function');
+      assert.strictEqual(typeof logger.sublog, 'function');
+      assert.strictEqual(typeof logger.on, 'function');
+      assert.ok(logger.instance instanceof al.AdhocDebugLogger);
+
+      const fields: al.LogFields = {
+        severity: al.LogSeverity.INFO,
+        telemetryTraceId: 'trace-123',
+        telemetrySpanId: 'span-456',
+        other: {'rpc.system': 'grpc'},
+      };
+      logger(fields, 'contract message %s', 'arg1');
+
+      assert.deepStrictEqual(sink.logs, [
+        {
+          namespace: 'contract-system',
+          fields,
+          args: ['contract message %s', 'arg1'],
+        },
+      ]);
+
+      const nodeBackend: al.DebugLogBackend = al.getNodeBackend();
+      assert.strictEqual(typeof nodeBackend.log, 'function');
+      assert.strictEqual(typeof nodeBackend.setFilters, 'function');
+
+      const structuredBackend: al.DebugLogBackend =
+        al.getStructuredBackend(nodeBackend);
+      assert.strictEqual(typeof structuredBackend.log, 'function');
+      assert.strictEqual(typeof structuredBackend.setFilters, 'function');
+    });
+  });
 });