chore(gax): add observability logging flag

core/packages/gax/src/clientInterface.ts

@@ -50,6 +50,16 @@ export interface ClientOptions
    * this option whenever it is set.
    */
   enableTelemetryTracing?: boolean;
+  /**
+   * Whether to enable telemetry logging for the client.
+   *
+   * Logging is only enabled when `GOOGLE_SDK_NODE_EXPERIMENTAL_LOGGING` is enabled
+   * AND either the `GOOGLE_SDK_NODE_ENABLE_LOGGING` environment variable is enabled
+   * or a user passes `enableTelemetryLogging: true` in their client options. The
+   * `GOOGLE_SDK_NODE_ENABLE_LOGGING` environment variable overrides this option
+   * whenever it is set.
+   */
+  enableTelemetryLogging?: boolean;
 }
 
 export interface Descriptors {

core/packages/gax/src/createApiCall.ts

@@ -41,7 +41,7 @@ import {
   traceAttempt,
   ResendRecorder,
 } from './observability/TracerHelper';
-import {checkTelemetryEnabled} from './observability/util';
+import {checkTracingEnabled} from './observability/util';
 import {
   StaticTraceContext,
   DynamicTraceContext,
@@ -83,7 +83,7 @@ export function createApiCall(
   // the following apiCaller will be used for all calls of this function...
   const apiCaller = createAPICaller(settings, descriptor);
 
-  const tracingEnabled = checkTelemetryEnabled(settings);
+  const tracingEnabled = checkTracingEnabled(settings);
   const staticArgs: StaticTraceContext | undefined = tracingEnabled
     ? resolveStaticTraceContext(settings)
     : undefined;

core/packages/gax/src/fallback.ts

@@ -110,6 +110,7 @@ export class GrpcClient {
   private _servicePath?: string;
   private _port?: number;
   private _enableTelemetryTracing?: boolean;
+  private _enableTelemetryLogging?: boolean;
 
   /**
    * In rare cases users might need to deallocate all memory consumed by loaded protos.
@@ -166,6 +167,9 @@ export class GrpcClient {
     this._enableTelemetryTracing = (
       options as GrpcClientOptions
     ).enableTelemetryTracing;
+    this._enableTelemetryLogging = (
+      options as GrpcClientOptions
+    ).enableTelemetryLogging;
   }
 
   /**
@@ -221,6 +225,8 @@ export class GrpcClient {
    * @param {Object} headers - A dictionary of additional HTTP header name to
    *   its value.
    * @param {boolean} [enableTelemetryTracing] - Flag to enable telemetry tracing.
+   * @param {unknown} [_legacyTelemetryInfo] - Unused legacy parameter kept for backward compatibility.
+   * @param {boolean} [enableTelemetryLogging] - Flag to enable telemetry logging.
    * @return {Object} A mapping of method names to CallSettings.
    */
   constructSettings(
@@ -231,6 +237,7 @@ export class GrpcClient {
     enableTelemetryTracing?: boolean,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     _legacyTelemetryInfo?: unknown,
+    enableTelemetryLogging?: boolean,
   ) {
     function buildMetadata(abTests: {}, moreHeaders: OutgoingHttpHeaders) {
       const metadata: OutgoingHttpHeaders = {};
@@ -305,6 +312,8 @@ export class GrpcClient {
       Status,
       otherArgs,
       enableTelemetryTracing ?? this._enableTelemetryTracing,
+      _legacyTelemetryInfo,
+      enableTelemetryLogging ?? this._enableTelemetryLogging,
     );
   }
 

core/packages/gax/src/gax.ts

@@ -24,7 +24,7 @@ import {warn} from './warnings';
 import {GoogleError} from './googleError';
 import {BundleOptions} from './bundlingCalls/bundleExecutor';
 import {toLowerCamelCase} from './util';
-import {checkTelemetryEnabled} from './observability/util';
+import {checkTracingEnabled, checkLoggingEnabled} from './observability/util';
 import {Status} from './status';
 import {RequestType} from './apitypes';
 
@@ -173,6 +173,7 @@ export interface CallOptions {
   apiName?: string;
   retryRequestOptions?: RetryRequestOptions;
   enableTelemetryTracing?: boolean;
+  enableTelemetryLogging?: boolean;
   /**
    * Internal context used by resumable upload methods. Populated by
    * GAPIC-generated client libraries; do not set manually.
@@ -195,6 +196,7 @@ export class CallSettings {
   apiName?: string;
   retryRequestOptions?: RetryRequestOptions;
   enableTelemetryTracing?: boolean;
+  enableTelemetryLogging?: boolean;
   resumableUpload?: ResumableUploadContext;
 
   /**
@@ -230,6 +232,7 @@ export class CallSettings {
     this.apiName = settings.apiName ?? undefined;
     this.retryRequestOptions = settings.retryRequestOptions;
     this.enableTelemetryTracing = settings.enableTelemetryTracing;
+    this.enableTelemetryLogging = settings.enableTelemetryLogging;
     this.resumableUpload =
       'resumableUpload' in settings ? settings.resumableUpload : undefined;
   }
@@ -256,6 +259,7 @@ export class CallSettings {
     let apiName = this.apiName;
     let retryRequestOptions = this.retryRequestOptions;
     let enableTelemetryTracing = this.enableTelemetryTracing;
+    let enableTelemetryLogging = this.enableTelemetryLogging;
     let resumableUpload = this.resumableUpload;
 
     // If the user provides a timeout to the method, that timeout value will be used
@@ -315,6 +319,9 @@ export class CallSettings {
     if ('enableTelemetryTracing' in options) {
       enableTelemetryTracing = options.enableTelemetryTracing;
     }
+    if ('enableTelemetryLogging' in options) {
+      enableTelemetryLogging = options.enableTelemetryLogging;
+    }
     if ('resumableUpload' in options) {
       resumableUpload = options.resumableUpload;
     }
@@ -331,6 +338,7 @@ export class CallSettings {
       apiName,
       retryRequestOptions,
       enableTelemetryTracing,
+      enableTelemetryLogging,
       resumableUpload,
     });
   }
@@ -807,6 +815,9 @@ export interface ClientConfig {
  *   calls.
  * @param {boolean} [enableTelemetryTracing] - Flag to enable telemetry tracing
  *   when passed in client options (or overridden by `GOOGLE_SDK_NODE_ENABLE_TRACING`).
+ * @param {unknown} [_legacyTelemetryInfo] - Unused legacy parameter kept for backward compatibility.
+ * @param {boolean} [enableTelemetryLogging] - Flag to enable telemetry logging
+ *   when passed in client options (or overridden by `GOOGLE_SDK_NODE_ENABLE_LOGGING`).
  * @return {Object} A mapping from method name to CallSettings, or null if the
  *   service is not found in the config.
  */
@@ -819,6 +830,7 @@ export function constructSettings(
   enableTelemetryTracing?: boolean,
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   _legacyTelemetryInfo?: unknown,
+  enableTelemetryLogging?: boolean,
 ) {
   const env: Record<string, string | undefined> =
     typeof process === 'object' && typeof process.env === 'object'
@@ -827,7 +839,7 @@ export function constructSettings(
   const envTracing = env.GOOGLE_SDK_NODE_ENABLE_TRACING?.trim();
   const isEnvSet = envTracing !== undefined && envTracing !== '';
 
-  const isEnvEnabled = checkTelemetryEnabled();
+  const isEnvEnabled = checkTracingEnabled();
 
   // Tracing is only enabled via GOOGLE_SDK_NODE_ENABLE_TRACING or when the user
   // passes enableTelemetryTracing: true in their client options. If
@@ -836,6 +848,18 @@ export function constructSettings(
     ? isEnvEnabled
     : Boolean(enableTelemetryTracing);
 
+  const experimentalLogging =
+    env.GOOGLE_SDK_NODE_EXPERIMENTAL_LOGGING?.trim().toLowerCase();
+  const isExperimentalLoggingEnabled =
+    experimentalLogging === 'true' || experimentalLogging === '1';
+  const envLogging = env.GOOGLE_SDK_NODE_ENABLE_LOGGING?.trim();
+  const isLoggingEnvSet = envLogging !== undefined && envLogging !== '';
+  const isLoggingEnvEnabled = checkLoggingEnabled();
+
+  const loggingRequested =
+    isExperimentalLoggingEnabled &&
+    (isLoggingEnvSet ? isLoggingEnvEnabled : Boolean(enableTelemetryLogging));
+
   otherArgs = otherArgs || {};
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const defaults: any = {};
@@ -893,11 +917,24 @@ export function constructSettings(
       bundleOptions: bundlingConfig
         ? createBundleOptions(bundlingConfig)
         : null,
-      otherArgs: tracingRequested
-        ? {...otherArgs, internalMethodName: methodName}
-        : otherArgs,
+      otherArgs:
+        tracingRequested || loggingRequested
+          ? {
+              ...otherArgs,
+              internalMethodName: methodName,
+              enableTelemetryTracing: tracingRequested,
+              enableTelemetryLogging: loggingRequested,
+            }
+          : otherArgs,
       apiName,
       enableTelemetryTracing: isEnvSet ? isEnvEnabled : enableTelemetryTracing,
+      enableTelemetryLogging: isExperimentalLoggingEnabled
+        ? isLoggingEnvSet
+          ? isLoggingEnvEnabled
+          : enableTelemetryLogging
+        : enableTelemetryLogging !== undefined || isLoggingEnvSet
+          ? false
+          : undefined,
     });
   }
 

core/packages/gax/src/grpc.ts

@@ -1,3 +1,3 @@
 /**
  * Copyright 2020 Google LLC
  *
@@ -63,6 +63,14 @@
    * options.
    */
   enableTelemetryTracing?: boolean;
+  /**
+   * Whether to enable telemetry logging for the client.
+   *
+   * Logging is only enabled when `GOOGLE_SDK_NODE_EXPERIMENTAL_LOGGING` is enabled
+   * AND either the `GOOGLE_SDK_NODE_ENABLE_LOGGING` environment variable is enabled
+   * or a user passes `enableTelemetryLogging: true` in their client options.
+   */
+  enableTelemetryLogging?: boolean;
 }
 
 export interface MetadataValue {
@@ -134,6 +142,7 @@
   private _servicePath?: string;
   private _port?: number;
   private _enableTelemetryTracing?: boolean;
+  private _enableTelemetryLogging?: boolean;
   /**
    * Base directory for resolving client certificates.
    *
@@ -193,6 +202,7 @@
         ? parseInt(options.port, 10)
         : options.port;
     this._enableTelemetryTracing = options.enableTelemetryTracing;
+    this._enableTelemetryLogging = options.enableTelemetryLogging;
 
     const minimumVersion = 10;
     const major = Number(process.version.match(/^v(\d+)/)?.[1]);
@@ -396,6 +406,8 @@
    * @param {Object} headers - A dictionary of additional HTTP header name to
    *   its value.
    * @param {boolean} [enableTelemetryTracing] - Flag to enable telemetry tracing.
+   * @param {unknown} [_legacyTelemetryInfo] - Unused legacy parameter kept for backward compatibility.
+   * @param {boolean} [enableTelemetryLogging] - Flag to enable telemetry logging.
    * @return {Object} A mapping of method names to CallSettings.
    */
   constructSettings(
@@ -406,6 +418,7 @@
     enableTelemetryTracing?: boolean,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     _legacyTelemetryInfo?: unknown,
+    enableTelemetryLogging?: boolean,
   ) {
     const otherArgs: Record<string, unknown> = {
       metadataBuilder: this.metadataBuilder(headers),
@@ -423,6 +436,8 @@
       this.grpc.status,
       otherArgs,
       enableTelemetryTracing ?? this._enableTelemetryTracing,
+      _legacyTelemetryInfo,
+      enableTelemetryLogging ?? this._enableTelemetryLogging,
     );
   }
 

core/packages/gax/src/index.ts

@@ -128,7 +128,7 @@ export {
 
 export {makeUUID, decodeAnyProtosInArray, decodeProtobufAny} from './util';
 
-export {checkTelemetryEnabled} from './observability/util';
+export {checkTracingEnabled} from './observability/util';
 export {
   StaticTraceContext,
   resolveStaticTraceContext,

core/packages/gax/src/observability/util.ts

@@ -27,7 +27,7 @@ import {CallSettings} from '../gax';
  * @param settings
  * @returns true if telemetry tracing is enabled, false otherwise
  */
-export function checkTelemetryEnabled(settings?: CallSettings): boolean {
+export function checkTracingEnabled(settings?: CallSettings): boolean {
   // `process` is undeclared in browsers and some edge runtimes, where reading
   // it would throw a ReferenceError rather than yield undefined, so it is
   // reached through a `typeof` guard and stands in as an empty environment.
@@ -47,3 +47,39 @@ export function checkTelemetryEnabled(settings?: CallSettings): boolean {
     settings?.otherArgs?.enableTelemetryTracing,
   );
 }
+
+/**
+ * Checks if telemetry logging is enabled.
+ *
+ * Logging is only enabled when `GOOGLE_SDK_NODE_EXPERIMENTAL_LOGGING` is enabled
+ * AND either the `GOOGLE_SDK_NODE_ENABLE_LOGGING` environment variable is enabled
+ * or a user passes `enableTelemetryLogging: true` in their client options.
+ * If `GOOGLE_SDK_NODE_ENABLE_LOGGING` is explicitly set, it takes precedence over
+ * the client option.
+ *
+ * @param settings
+ * @returns true if telemetry logging is enabled, false otherwise
+ */
+export function checkLoggingEnabled(settings?: CallSettings): boolean {
+  const env: Record<string, string | undefined> =
+    typeof process === 'object' && typeof process.env === 'object'
+      ? process.env
+      : {};
+  const experimentalOptIn =
+    env.GOOGLE_SDK_NODE_EXPERIMENTAL_LOGGING?.trim().toLowerCase();
+  if (experimentalOptIn !== 'true' && experimentalOptIn !== '1') {
+    return false;
+  }
+
+  const envOptIn = env.GOOGLE_SDK_NODE_ENABLE_LOGGING?.trim();
+
+  if (envOptIn !== undefined && envOptIn !== '') {
+    const lower = envOptIn.toLowerCase();
+    return lower === 'true' || lower === '1';
+  }
+
+  return Boolean(
+    settings?.enableTelemetryLogging ||
+    settings?.otherArgs?.enableTelemetryLogging,
+  );
+}

core/packages/gax/test/unit/exports.ts

@@ -62,8 +62,8 @@ describe('exports', () => {
     it('exports protobufMinimal', () => {
       assert(typeof index.protobufMinimal === 'object');
     });
-    it('exports checkTelemetryEnabled', () => {
-      assert(typeof index.checkTelemetryEnabled === 'function');
+    it('exports checkTracingEnabled', () => {
+      assert(typeof index.checkTracingEnabled === 'function');
     });
     it('exports resolveStaticTraceContext', () => {
       assert(typeof index.resolveStaticTraceContext === 'function');