feat(metrics): add ability to pass custom logger

Author: dreamorosi

packages/commons/src/types/GenericLogger.ts

@@ -0,0 +1,17 @@
+// biome-ignore lint/suspicious/noExplicitAny: We intentionally use `any` here to represent any type of data and keep the logger is as flexible as possible.
+type Anything = any[];
+
+/**
+ * Interface for a generic logger object.
+ *
+ * This interface is used to define the shape of a logger object that can be passed to a Powertools for AWS utility.
+ *
+ * It can be an instance of Logger from Powertools for AWS, or any other logger that implements the same methods.
+ */
+export interface GenericLogger {
+  trace?: (...content: Anything) => void;
+  debug: (...content: Anything) => void;
+  info: (...content: Anything) => void;
+  warn: (...content: Anything) => void;
+  error: (...content: Anything) => void;
+}

packages/commons/src/types/index.ts

@@ -5,6 +5,7 @@ export type {
   MiddlewareFn,
   CleanupFunction,
 } from './middy.js';
+export type { GenericLogger } from './GenericLogger.js';
 export type { SdkClient, MiddlewareArgsLike } from './awsSdk.js';
 export type {
   JSONPrimitive,

packages/metrics/src/Metrics.ts

@@ -1,6 +1,9 @@
 import { Console } from 'node:console';
 import { Utility } from '@aws-lambda-powertools/commons';
-import type { HandlerMethodDecorator } from '@aws-lambda-powertools/commons/types';
+import type {
+  GenericLogger,
+  HandlerMethodDecorator,
+} from '@aws-lambda-powertools/commons/types';
 import type { Callback, Context, Handler } from 'aws-lambda';
 import { EnvironmentVariablesService } from './config/EnvironmentVariablesService.js';
 import {
@@ -149,6 +152,11 @@ class Metrics extends Utility implements MetricsInterface {
    */
   private functionName?: string;
 
+  /**
+   * Custom logger object to be used for emitting debug, warning, and error messages.
+   */
+  #logger?: GenericLogger;
+
   /**
    * Flag indicating if this is a single metric instance
    * @default false
@@ -182,6 +190,7 @@ class Metrics extends Utility implements MetricsInterface {
     super();
 
     this.dimensions = {};
+    this.#logger = options.logger;
     this.setOptions(options);
   }
 
@@ -347,6 +356,13 @@ class Metrics extends Utility implements MetricsInterface {
     this.storedMetrics = {};
   }
 
+  /**
+   * Check if there are stored metrics in the buffer.
+   */
+  public hasStoredMetrics(): boolean {
+    return Object.keys(this.storedMetrics).length > 0;
+  }
+
   /**
    * A decorator automating coldstart capture, throw on empty metrics and publishing metrics on handler exit.
    *
@@ -428,12 +444,16 @@ class Metrics extends Utility implements MetricsInterface {
    * ```
    */
   public publishStoredMetrics(): void {
-    const hasMetrics = Object.keys(this.storedMetrics).length > 0;
+    const hasMetrics = this.hasStoredMetrics();
     if (!this.shouldThrowOnEmptyMetrics && !hasMetrics) {
-      console.warn(
+      const message =
         'No application metrics to publish. The cold-start metric may be published if enabled. ' +
-          'If application metrics should never be empty, consider using `throwOnEmptyMetrics`'
-      );
+        'If application metrics should never be empty, consider using `throwOnEmptyMetrics`';
+      if (this.#logger?.warn) {
+        this.#logger.warn(message);
+      } else {
+        this.console.warn(message);
+      }
     }
     const emfOutput = this.serializeMetrics();
     hasMetrics && this.console.log(JSON.stringify(emfOutput));
@@ -471,7 +491,9 @@ class Metrics extends Utility implements MetricsInterface {
     }
 
     if (!this.namespace)
-      console.warn('Namespace should be defined, default used');
+      (this.#logger?.warn || this.console.warn)(
+        'Namespace should be defined, default used'
+      );
 
     // We reduce the stored metrics to a single object with the metric
     // name as the key and the value as the value.

packages/metrics/src/types/Metrics.ts

@@ -1,3 +1,4 @@
+import type { GenericLogger } from '@aws-lambda-powertools/commons/types';
 import type {
   MetricResolution as MetricResolutionList,
   MetricUnit as MetricUnitList,
@@ -12,6 +13,15 @@ type MetricsOptions = {
   serviceName?: string;
   singleMetric?: boolean;
   defaultDimensions?: Dimensions;
+  /**
+   * Logger object to be used for emitting debug, warning, and error messages.
+   *
+   * If not provided, debug messages will be suppressed, and warning and error messages will be sent to stdout.
+   *
+   * Note that EMF metrics are always sent directly to stdout, regardless of the logger
+   * to avoid any potential side effects from using a custom logger.
+   */
+  logger?: GenericLogger;
 };
 
 type EmfOutput = Readonly<{

packages/metrics/tests/unit/Metrics.test.ts

@@ -4,6 +4,7 @@
  * @group unit/metrics/class
  */
 import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
+import { Logger } from '@aws-lambda-powertools/logger';
 import context from '@aws-lambda-powertools/testing-utils/context';
 import type { Context, Handler } from 'aws-lambda';
 import { EnvironmentVariablesService } from '../../src/config/EnvironmentVariablesService.js';
@@ -27,6 +28,8 @@ jest.mock('node:console', () => ({
   ...jest.requireActual('node:console'),
   Console: jest.fn().mockImplementation(() => ({
     log: jest.fn(),
+    warn: jest.fn(),
+    debug: jest.fn(),
   })),
 }));
 jest.spyOn(console, 'warn').mockImplementation(() => ({}));
@@ -1254,7 +1257,10 @@ describe('Class: Metrics', () => {
   describe('Methods: publishStoredMetrics', () => {
     test('it should log warning if no metrics are added & throwOnEmptyMetrics is false', () => {
       // Prepare
-      const metrics: Metrics = new Metrics({ namespace: TEST_NAMESPACE });
+      const metrics: Metrics = new Metrics({
+        namespace: TEST_NAMESPACE,
+        logger: console,
+      });
       const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
       const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation();
 
@@ -1355,7 +1361,7 @@ describe('Class: Metrics', () => {
     test('it should print warning, if no namespace provided in constructor or environment variable', () => {
       // Prepare
       process.env.POWERTOOLS_METRICS_NAMESPACE = '';
-      const metrics: Metrics = new Metrics();
+      const metrics: Metrics = new Metrics({ logger: console });
       const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
 
       // Act

packages/metrics/tests/unit/middleware/middy.test.ts

@@ -14,6 +14,8 @@ jest.mock('node:console', () => ({
   ...jest.requireActual('node:console'),
   Console: jest.fn().mockImplementation(() => ({
     log: jest.fn(),
+    warn: jest.fn(),
+    debug: jest.fn(),
   })),
 }));
 jest.spyOn(console, 'warn').mockImplementation(() => ({}));
@@ -68,6 +70,7 @@ describe('Middy middleware', () => {
       const metrics = new Metrics({
         namespace: 'serverlessAirline',
         serviceName: 'orders',
+        logger: console,
       });
       const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
       const handler = middy(async (): Promise<void> => undefined).use(