feat(logger): introduce log key reordering functionality

packages/logger/src/Logger.ts

@@ -24,6 +24,7 @@ import type {
   LogItemMessage,
   LoggerInterface,
   PowertoolsLogData,
+  UnformattedAttributes,
 } from './types/Logger.js';
 
 /**
@@ -1080,12 +1081,19 @@ class Logger extends Utility implements LoggerInterface {
    *
    * @private
    * @param {LogFormatterInterface} logFormatter
+   * @param {Array<keyof UnformattedAttributes>} logRecordOrder
    * @returns {void}
    */
-  private setLogFormatter(logFormatter?: LogFormatterInterface): void {
+  private setLogFormatter(
+    logFormatter?: LogFormatterInterface,
+    logRecordOrder?: Array<keyof UnformattedAttributes>
+  ): void {
     this.logFormatter =
       logFormatter ??
-      new PowertoolsLogFormatter({ envVarsService: this.getEnvVarsService() });
+      new PowertoolsLogFormatter({
+        envVarsService: this.getEnvVarsService(),
+        logRecordOrder,
+      });
   }
 
   /**
@@ -1119,6 +1127,7 @@ class Logger extends Utility implements LoggerInterface {
       persistentKeys,
       persistentLogAttributes, // deprecated in favor of persistentKeys
       environment,
+      logRecordOrder,
     } = options;
 
     if (persistentLogAttributes && persistentKeys) {
@@ -1140,7 +1149,7 @@ class Logger extends Utility implements LoggerInterface {
     this.setInitialSampleRate(sampleRateValue);
 
     // configurations that affect how logs are printed
-    this.setLogFormatter(logFormatter);
+    this.setLogFormatter(logFormatter, logRecordOrder);
     this.setConsole();
     this.setLogIndentation();
 

packages/logger/src/formatter/LogFormatter.ts

@@ -21,8 +21,14 @@ abstract class LogFormatter implements LogFormatterInterface {
    */
   protected envVarsService?: EnvironmentVariablesService;
 
+  /**
+   * An array of keys that defines the order of the log record.
+   */
+  protected logRecordOrder?: Array<keyof UnformattedAttributes>;
+
   public constructor(options?: LogFormatterOptions) {
     this.envVarsService = options?.envVarsService;
+    this.logRecordOrder = options?.logRecordOrder;
   }
 
   /**

packages/logger/src/formatter/PowertoolsLogFormatter.ts

@@ -1,3 +1,4 @@
+import merge from 'lodash.merge';
 import type { LogAttributes, PowertoolsLog } from '../types/Log.js';
 import type { UnformattedAttributes } from '../types/Logger.js';
 import { LogFormatter } from './LogFormatter.js';
@@ -35,7 +36,22 @@ class PowertoolsLogFormatter extends LogFormatter {
       timestamp: this.formatTimestamp(attributes.timestamp),
       xray_trace_id: attributes.xRayTraceId,
     };
-    const powertoolsLogItem = new LogItem({ attributes: baseAttributes });
+
+    const orderedAttributes = {} as PowertoolsLog;
+
+    // If logRecordOrder is set, order the attributes in the log item
+    this.logRecordOrder?.forEach((key) => {
+      if (key in baseAttributes) {
+        orderedAttributes[key] = baseAttributes[key];
+        delete baseAttributes[key];
+      }
+    });
+
+    // Merge the ordered attributes with the rest of the attributes
+    const powertoolsLogItem = new LogItem({
+      attributes: merge(orderedAttributes, baseAttributes),
+    });
+
     powertoolsLogItem.addAttributes(additionalLogAttributes);
 
     return powertoolsLogItem;

packages/logger/src/types/Log.ts

@@ -132,6 +132,8 @@ type LogFormatterOptions = {
    * If set, it gives the LogFormatter access to environment variables.
    */
   envVarsService?: EnvironmentVariablesService;
+
+  logRecordOrder?: Array<keyof UnformattedAttributes>;
 };
 
 /**

packages/logger/src/types/Logger.ts

@@ -35,6 +35,7 @@ type BaseConstructorOptions = {
   logFormatter?: LogFormatterInterface;
   customConfigService?: ConfigServiceInterface;
   environment?: Environment;
+  logRecordOrder?: Array<keyof UnformattedAttributes>;
 };
 
 type PersistentKeysOption = {

packages/logger/tests/unit/formatter/PowertoolsLogFormatter.test.ts

@@ -102,6 +102,60 @@ describe('Class: PowertoolsLogFormatter', () => {
         xray_trace_id: '1-5759e988-bd862e3fe1be46a994272793',
       });
     });
+
+    test('when logRecordOrder is set, it orders the attributes in the log item', () => {
+      // Prepare
+      const formatter = new PowertoolsLogFormatter({
+        logRecordOrder: ['message', 'timestamp', 'serviceName', 'environment'],
+      });
+      const unformattedAttributes: UnformattedAttributes = {
+        sampleRateValue: 0.25,
+        awsRegion: 'eu-west-1',
+        environment: 'prod',
+        serviceName: 'hello-world',
+        xRayTraceId: '1-5759e988-bd862e3fe1be46a994272793',
+        logLevel: 'WARN',
+        timestamp: new Date(),
+        message: 'This is a WARN log',
+        error: new Error('Something happened!'),
+        lambdaContext: {
+          functionName: 'my-lambda-function',
+          memoryLimitInMB: '123',
+          functionVersion: '1.23.3',
+          coldStart: true,
+          invokedFunctionArn:
+            'arn:aws:lambda:eu-west-1:123456789012:function:Example',
+          awsRequestId: 'abcdefg123456789',
+        },
+      };
+      const additionalLogAttributes: LogAttributes = {};
+
+      // Act
+      const value = formatter.formatAttributes(
+        unformattedAttributes,
+        additionalLogAttributes
+      );
+
+      const response = value.getAttributes();
+
+      // Assess
+      expect(JSON.stringify(response)).toEqual(
+        JSON.stringify({
+          message: 'This is a WARN log',
+          timestamp: '2016-06-20T12:08:10.000Z',
+          cold_start: true,
+          function_arn:
+            'arn:aws:lambda:eu-west-1:123456789012:function:Example',
+          function_memory_size: '123',
+          function_name: 'my-lambda-function',
+          function_request_id: 'abcdefg123456789',
+          level: 'WARN',
+          sampling_rate: 0.25,
+          service: 'hello-world',
+          xray_trace_id: '1-5759e988-bd862e3fe1be46a994272793',
+        })
+      );
+    });
   });
 
   describe('Method: formatError', () => {