feat(api-logs, sdk-logs)!: add Logger#enabled method

experimental/CHANGELOG.md

@@ -8,6 +8,8 @@ For notes on migrating to 2.x / 0.200.x see [the upgrade guide](doc/upgrade-to-2
 
 ### :boom: Breaking Changes
 
+* feat(api-logs, sdk-logs)!: add `enabled` method to Logger interface and implementi it in logs API and SDK [#6371](https://github.com/open-telemetry/opentelemetry-js/pull/6371) @david-luna
+
 ### :rocket: Features
 
 ### :bug: Bug Fixes

experimental/packages/api-logs/src/NoopLogger.ts

@@ -8,6 +8,9 @@ import type { LogRecord } from './types/LogRecord';
 
 export class NoopLogger implements Logger {
   emit(_logRecord: LogRecord): void {}
+  enabled(): boolean {
+    return false;
+  }
 }
 
 export const NOOP_LOGGER = new NoopLogger();

experimental/packages/api-logs/src/ProxyLogger.ts

@@ -3,10 +3,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import type { Context } from '@opentelemetry/api';
 import { NOOP_LOGGER } from './NoopLogger';
 import type { Logger } from './types/Logger';
 import type { LoggerOptions } from './types/LoggerOptions';
 import type { LogRecord } from './types/LogRecord';
+import type { SeverityNumber } from './types/LogRecord';
 
 export class ProxyLogger implements Logger {
   // When a real implementation is provided, this will be it
@@ -37,6 +39,14 @@ export class ProxyLogger implements Logger {
     this._getLogger().emit(logRecord);
   }
 
+  enabled(options?: {
+    context?: Context;
+    severityNumber?: SeverityNumber;
+    eventName?: string;
+  }): boolean {
+    return this._getLogger().enabled(options);
+  }
+
   /**
    * Try to get a logger from the proxy logger provider.
    * If the proxy logger provider has no delegate, return a noop logger.

experimental/packages/api-logs/src/types/Logger.ts

@@ -3,7 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import type { Context } from '@opentelemetry/api';
 import type { LogRecord } from './LogRecord';
+import type { SeverityNumber } from './LogRecord';
 
 export interface Logger {
   /**
@@ -12,4 +14,14 @@ export interface Logger {
    * @param logRecord
    */
   emit(logRecord: LogRecord): void;
+
+  /**
+   * Will a log record with the given details get emitted?
+   * This can be used to avoid expensive calculation of log record data.
+   */
+  enabled(options?: {
+    context?: Context;
+    severityNumber?: SeverityNumber;
+    eventName?: string;
+  }): boolean;
 }

experimental/packages/api-logs/test/noop-implementations/noop-logger.test.ts

@@ -21,4 +21,9 @@ describe('NoopLogger', () => {
       body: 'log body',
     });
   });
+
+  it('calling enabled should return false', () => {
+    const logger = new NoopLoggerProvider().getLogger('test-noop');
+    assert.ok(!logger.enabled());
+  });
 });

experimental/packages/api-logs/test/proxy-implementations/proxy-logger.test.ts

@@ -74,13 +74,18 @@ describe('ProxyLogger', () => {
 
     let delegateLogger: Logger;
     let emitCalled: boolean;
+    let enabledCalled: boolean;
 
     beforeEach(() => {
       emitCalled = false;
       delegateLogger = {
         emit() {
           emitCalled = true;
         },
+        enabled() {
+          enabledCalled = true;
+          return true;
+        },
       };
 
       logger = provider.getLogger('test');
@@ -99,5 +104,10 @@ describe('ProxyLogger', () => {
       });
       assert.ok(emitCalled);
     });
+
+    it('should call enabled from the delegate logger', () => {
+      logger.enabled();
+      assert.ok(enabledCalled);
+    });
   });
 });

experimental/packages/sdk-logs/src/LogRecordProcessor.ts

@@ -4,8 +4,9 @@
  */
 
 import type { Context } from '@opentelemetry/api';
-
+import type { InstrumentationScope } from '@opentelemetry/core';
 import type { SdkLogRecord } from './export/SdkLogRecord';
+import type { SeverityNumber } from '@opentelemetry/api-logs';
 
 export interface LogRecordProcessor {
   /**
@@ -25,4 +26,16 @@ export interface LogRecordProcessor {
    * opportunity for processor to do any cleanup required.
    */
   shutdown(): Promise<void>;
+
+  /**
+   * Tells if the logger is enabled for the given context, severity number and event
+   * name if provided.
+   * @param options
+   */
+  enabled?(options: {
+    context: Context;
+    instrumentationScope: InstrumentationScope;
+    severityNumber?: SeverityNumber;
+    eventName?: string;
+  }): boolean;
 }

experimental/packages/sdk-logs/src/Logger.ts

@@ -6,6 +6,7 @@
 import type * as logsAPI from '@opentelemetry/api-logs';
 import { SeverityNumber } from '@opentelemetry/api-logs';
 import type { InstrumentationScope } from '@opentelemetry/core';
+import type { Context } from '@opentelemetry/api';
 import {
   context,
   trace,
@@ -97,4 +98,53 @@ export class Logger implements logsAPI.Logger {
      */
     logRecordInstance._makeReadonly();
   }
+
+  public enabled(options?: {
+    context?: Context;
+    severityNumber?: SeverityNumber;
+    eventName?: string;
+  }): boolean {
+    const loggerConfig = this._loggerConfig;
+
+    if (loggerConfig.disabled) {
+      return false;
+    }
+
+    // Severity number given and lower than the min configured
+    const severityNumber = options?.severityNumber;
+    if (
+      typeof severityNumber === 'number' &&
+      severityNumber !== SeverityNumber.UNSPECIFIED &&
+      severityNumber < loggerConfig.minimumSeverity
+    ) {
+      return false;
+    }
+
+    const currentContext = options?.context || context.active();
+    // Trace based: the context (given or the active) has a unsampled Span
+    if (loggerConfig.traceBased) {
+      const spanContext = trace.getSpanContext(currentContext);
+      if (spanContext && isSpanContextValid(spanContext)) {
+        const isSampled =
+          (spanContext.traceFlags & TraceFlags.SAMPLED) === TraceFlags.SAMPLED;
+        if (!isSampled) {
+          return false;
+        }
+      }
+    }
+
+    // Lastly check if there is any enabled processor
+    const enabledOpts = {
+      context: currentContext,
+      instrumentationScope: this.instrumentationScope,
+      severityNumber: options?.severityNumber,
+      eventName: options?.eventName,
+    };
+    for (const processor of this._sharedState.processors) {
+      if (!processor.enabled || processor.enabled(enabledOpts)) {
+        return true;
+      }
+    }
+    return false;
+  }
 }

experimental/packages/sdk-logs/src/MultiLogRecordProcessor.ts

@@ -3,10 +3,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import type { InstrumentationScope } from '@opentelemetry/core';
 import { callWithTimeout } from '@opentelemetry/core';
 import type { Context } from '@opentelemetry/api';
 import type { LogRecordProcessor } from './LogRecordProcessor';
 import type { SdkLogRecord } from './export/SdkLogRecord';
+import type { SeverityNumber } from '@opentelemetry/api-logs';
 
 /**
  * Implementation of the {@link LogRecordProcessor} that simply forwards all
@@ -41,4 +43,18 @@ export class MultiLogRecordProcessor implements LogRecordProcessor {
   public async shutdown(): Promise<void> {
     await Promise.all(this.processors.map(processor => processor.shutdown()));
   }
+
+  public enabled(options: {
+    context: Context;
+    instrumentationScope: InstrumentationScope;
+    severityNumber?: SeverityNumber;
+    eventName?: string;
+  }): boolean {
+    for (const processor of this.processors) {
+      if (!processor.enabled || processor.enabled(options)) {
+        return true;
+      }
+    }
+    return false;
+  }
 }

experimental/packages/sdk-logs/src/export/NoopLogRecordProcessor.ts

@@ -3,18 +3,29 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import type { InstrumentationScope } from '@opentelemetry/core';
 import type { Context } from '@opentelemetry/api';
 import type { LogRecordProcessor } from '../LogRecordProcessor';
 import type { ReadableLogRecord } from './ReadableLogRecord';
+import type { SeverityNumber } from '@opentelemetry/api-logs';
 
 export class NoopLogRecordProcessor implements LogRecordProcessor {
-  forceFlush(): Promise<void> {
+  public forceFlush(): Promise<void> {
     return Promise.resolve();
   }
 
-  onEmit(_logRecord: ReadableLogRecord, _context: Context): void {}
+  public onEmit(_logRecord: ReadableLogRecord, _context: Context): void {}
 
-  shutdown(): Promise<void> {
+  public shutdown(): Promise<void> {
     return Promise.resolve();
   }
+
+  public enabled(_options: {
+    context: Context;
+    instrumentationScope: InstrumentationScope;
+    severityNumber?: SeverityNumber;
+    eventName?: string;
+  }): boolean {
+    return false;
+  }
 }