feat(api): Optionally suppress warning about logger being overwritten

api/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## Unreleased
+
+### Features
+
+* Optionally suppress warning about logger being overwritten ([#3366](https://www.github.com/open-telemetry/opentelemetry-js-api/pull/3366))
+
 ## [1.2.0](https://www.github.com/open-telemetry/opentelemetry-js-api/compare/v1.1.0...v1.2.0) (2022-08-09)
 
 ### Features

api/src/api/diag.ts

@@ -20,6 +20,7 @@ import {
   ComponentLoggerOptions,
   DiagLogFunction,
   DiagLogger,
+  DiagLoggerApi,
   DiagLogLevel,
 } from '../diag/types';
 import {
@@ -34,7 +35,7 @@ const API_NAME = 'diag';
  * Singleton object which represents the entry point to the OpenTelemetry internal
  * diagnostic API
  */
-export class DiagAPI implements DiagLogger {
+export class DiagAPI implements DiagLogger, DiagLoggerApi {
   private static _instance?: DiagAPI;
 
   /** Get the singleton instance of the DiagAPI API */
@@ -65,9 +66,9 @@ export class DiagAPI implements DiagLogger {
 
     // DiagAPI specific functions
 
-    self.setLogger = (
-      logger: DiagLogger,
-      logLevel: DiagLogLevel = DiagLogLevel.INFO
+    const setLogger: DiagLoggerApi['setLogger'] = (
+      logger,
+      optionsOrLogLevel = { logLevel: DiagLogLevel.INFO },
     ) => {
       if (logger === self) {
         // There isn't much we can do here.
@@ -80,10 +81,16 @@ export class DiagAPI implements DiagLogger {
         return false;
       }
 
+      if (typeof optionsOrLogLevel === 'number') {
+        optionsOrLogLevel = {
+          logLevel: optionsOrLogLevel,
+        };
+      }
+
       const oldLogger = getGlobal('diag');
-      const newLogger = createLogLevelDiagLogger(logLevel, logger);
+      const newLogger = createLogLevelDiagLogger(optionsOrLogLevel.logLevel ?? DiagLogLevel.INFO, logger);
       // There already is an logger registered. We'll let it know before overwriting it.
-      if (oldLogger) {
+      if (oldLogger && !optionsOrLogLevel.suppressOverrideMessage) {
         const stack = new Error().stack ?? '<failed to generate stacktrace>';
         oldLogger.warn(`Current logger will be overwritten from ${stack}`);
         newLogger.warn(
@@ -94,6 +101,8 @@ export class DiagAPI implements DiagLogger {
       return registerGlobal('diag', newLogger, self, true);
     };
 
+    self.setLogger = setLogger;
+
     self.disable = () => {
       unregisterGlobal(API_NAME, self);
     };
@@ -109,15 +118,7 @@ export class DiagAPI implements DiagLogger {
     self.error = _logProxy('error');
   }
 
-  /**
-   * Set the global DiagLogger and DiagLogLevel.
-   * If a global diag logger is already set, this will override it.
-   *
-   * @param logger - [Optional] The DiagLogger instance to set as the default logger.
-   * @param logLevel - [Optional] The DiagLogLevel used to filter logs sent to the logger. If not provided it will default to INFO.
-   * @returns true if the logger was successfully registered, else false
-   */
-  public setLogger!: (logger: DiagLogger, logLevel?: DiagLogLevel) => boolean;
+  public setLogger!: DiagLoggerApi['setLogger'];
   /**
    *
    */

api/src/diag/types.ts

@@ -96,3 +96,37 @@ export enum DiagLogLevel {
 export interface ComponentLoggerOptions {
   namespace: string;
 }
+
+export interface LoggerOptions {
+  /**
+   * The {@link DiagLogLevel} used to filter logs sent to the logger.
+   * 
+   * @defaultValue DiagLogLevel.INFO
+   */
+  logLevel?: DiagLogLevel;
+
+  /**
+   * Setting this value to `true` will suppress the warning message normally emitted when registering a logger when another logger is already registered.
+   */
+  suppressOverrideMessage?: boolean;
+}
+
+export interface DiagLoggerApi {
+  /**
+  * Set the global DiagLogger and DiagLogLevel.
+  * If a global diag logger is already set, this will override it.
+  *
+  * @param logger - [Optional] The {@link DiagLogger} instance to set as the default logger.
+  * @param options - [Optional] A {@link LoggerOptions} object.
+  * @returns `true` if the logger was successfully registered, else `false`
+  */
+  setLogger(logger: DiagLogger, options?: LoggerOptions): boolean;
+
+  /**
+   *
+   * @param logger - [Optional] The {@link DiagLogger} instance to set as the default logger.
+   * @param logLevel - [Optional] The {@link DiagLogLevel} used to filter logs sent to the logger. If not provided it will default to {@link DiagLogLevel.INFO}.
+   * @returns `true` if the logger was successfully registered, else `false`
+   */
+  setLogger(logger: DiagLogger, logLevel?: DiagLogLevel): boolean;
+}