feat(logger): introduce log key reordering functionality

docs/core/logger.md

@@ -542,6 +542,22 @@ We prioritise log level settings in this order:
 
 In the event you have set a log level in Powertools to a level that is lower than the ACL setting, we will output a warning log message informing you that your messages will be discarded by Lambda.
 
+### Reordering log keys position
+
+You can change the order of [standard Logger keys](#standard-structured-keys) or any keys that will be appended later at runtime via the `logRecordOrder` parameter.
+
+=== "reorderLogKeys.ts"
+
+    ```typescript hl_lines="5 10"
+    --8<-- "examples/snippets/logger/reorderLogKeys.ts"
+    ```
+
+=== "reorderLogKeysOutput.json"
+
+    ```json hl_lines="2-3"
+    --8<-- "examples/snippets/logger/reorderLogKeysOutput.json"
+    ```
+
 ### Setting timestamp to custom Timezone
 
 By default, Logger emits records with the default Lambda timestamp in **UTC**, i.e. `2016-06-20T12:08:10.000Z`

examples/snippets/logger/reorderLogKeys.ts

@@ -0,0 +1,12 @@
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger({
+  serviceName: 'serverlessAirline',
+  logRecordOrder: ['timestamp', 'additionalKey'],
+});
+
+export const handler = async (): Promise<void> => {
+  logger.info('Hello, World!', {
+    additionalKey: 'additionalValue',
+  });
+};

examples/snippets/logger/reorderLogKeysOutput.json

@@ -0,0 +1,9 @@
+{
+  "timestamp": "2024-09-03T02:59:06.603Z",
+  "additionalKey": "additionalValue",
+  "level": "INFO",
+  "message": "Hello, World!",
+  "sampling_rate": 0,
+  "service": "serverlessAirline",
+  "xray_trace_id": "1-66d67b7a-79bc7b2346b32af01b437cf8"
+}

packages/logger/src/Logger.ts

@@ -23,6 +23,7 @@ import type {
   LogFunction,
   LogItemExtraInput,
   LogItemMessage,
+  LogRecordOrder,
   LoggerInterface,
   PowertoolsLogData,
 } from './types/Logger.js';
@@ -1081,11 +1082,18 @@ class Logger extends Utility implements LoggerInterface {
    *
    * @private
    * @param {LogFormatterInterface} logFormatter - The log formatt er
+   * @param {LogRecordOrder} logRecordOrder
    */
-  private setLogFormatter(logFormatter?: LogFormatterInterface): void {
+  private setLogFormatter(
+    logFormatter?: LogFormatterInterface,
+    logRecordOrder?: LogRecordOrder
+  ): 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 {
       persistentLogAttributes, // deprecated in favor of persistentKeys
       environment,
       jsonReplacerFn,
+      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();
     this.#jsonReplacerFn = jsonReplacerFn;

packages/logger/src/formatter/LogFormatter.ts

@@ -4,7 +4,7 @@ import type {
   LogFormatterInterface,
   LogFormatterOptions,
 } from '../types/Log.js';
-import type { UnformattedAttributes } from '../types/Logger.js';
+import type { LogRecordOrder, UnformattedAttributes } from '../types/Logger.js';
 import type { LogItem } from './LogItem.js';
 
 /**
@@ -19,8 +19,14 @@ abstract class LogFormatter implements LogFormatterInterface {
    */
   protected envVarsService?: EnvironmentVariablesService;
 
+  /**
+   * An array of keys that defines the order of the log record.
+   */
+  protected logRecordOrder?: LogRecordOrder;
+
   public constructor(options?: LogFormatterOptions) {
     this.envVarsService = options?.envVarsService;
+    this.logRecordOrder = options?.logRecordOrder;
   }
 
   /**

packages/logger/src/formatter/PowertoolsLogFormatter.ts

@@ -34,8 +34,38 @@ class PowertoolsLogFormatter extends LogFormatter {
       timestamp: this.formatTimestamp(attributes.timestamp),
       xray_trace_id: attributes.xRayTraceId,
     };
-    const powertoolsLogItem = new LogItem({ attributes: baseAttributes });
-    powertoolsLogItem.addAttributes(additionalLogAttributes);
+
+    const orderedAttributes = {} as PowertoolsLog;
+
+    // If logRecordOrder is set, order the attributes in the log item
+    for (const key of this.logRecordOrder || []) {
+      if (key in baseAttributes && !(key in orderedAttributes)) {
+        orderedAttributes[key] = baseAttributes[key];
+      } else if (
+        key in additionalLogAttributes &&
+        !(key in orderedAttributes)
+      ) {
+        orderedAttributes[key] = additionalLogAttributes[key];
+      }
+    }
+
+    // Add remaining attributes from baseAttributes
+    for (const key in baseAttributes) {
+      if (!(key in orderedAttributes)) {
+        orderedAttributes[key] = baseAttributes[key];
+      }
+    }
+
+    // Add remaining attributes from additionalLogAttributes
+    for (const key in additionalLogAttributes) {
+      if (!(key in orderedAttributes)) {
+        orderedAttributes[key] = additionalLogAttributes[key];
+      }
+    }
+
+    const powertoolsLogItem = new LogItem({
+      attributes: orderedAttributes,
+    });
 
     return powertoolsLogItem;
   }

packages/logger/src/types/Log.ts

@@ -1,7 +1,7 @@
 import type { EnvironmentVariablesService } from '../config/EnvironmentVariablesService.js';
 import type { LogLevel as LogLevelList } from '../constants.js';
 import type { LogItem } from '../formatter/LogItem.js';
-import type { UnformattedAttributes } from './Logger.js';
+import type { LogRecordOrder, UnformattedAttributes } from './Logger.js';
 
 type LogLevel =
   | (typeof LogLevelList)[keyof typeof LogLevelList]
@@ -125,6 +125,8 @@ type LogFormatterOptions = {
    * If set, it gives the LogFormatter access to environment variables.
    */
   envVarsService?: EnvironmentVariablesService;
+
+  logRecordOrder?: LogRecordOrder;
 };
 
 /**

packages/logger/src/types/Logger.ts

@@ -85,6 +85,7 @@ type BaseConstructorOptions = {
    * This allows you to customize the serialization while still benefiting from the default behavior.
    */
   jsonReplacerFn?: CustomJsonReplacerFn;
+  logRecordOrder?: LogRecordOrder;
 };
 
 /**
@@ -157,6 +158,8 @@ type UnformattedAttributes = PowertoolsLogData & {
   message: string;
 };
 
+type LogRecordOrder = Array<keyof UnformattedAttributes | keyof LogAttributes>;
+
 type LogItemMessage = string | LogAttributesWithMessage;
 type LogItemExtraInput = [Error | string] | LogAttributes[];
 
@@ -197,4 +200,5 @@ export type {
   ConstructorOptions,
   InjectLambdaContextOptions,
   CustomJsonReplacerFn,
+  LogRecordOrder,
 };