Docs: add notice about mutating attributes in custom log formatters

[VladimirGorobetsWildix]

Expected Behavior

No change original event fields.

Current Behavior

Original event fields changed in logFormatter after upgrade 2.13.1 -> 2.14.0

Code snippet

import middy from '@middy/core'
import {LogFormatter, Logger, LogItem} from "@aws-lambda-powertools/logger";
import type {LogAttributes, UnformattedAttributes} from '@aws-lambda-powertools/logger/types';
import {injectLambdaContext} from "@aws-lambda-powertools/logger/middleware";


class MyCompanyLogFormatter extends LogFormatter {
    private hideFields = [
        'authorization',
        'password',
        'secret',
        'key',
        'token',
    ]

    processObject(obj: Record<string, any>) {
        for (const key in obj) {
            if (typeof obj[key] === 'object') {
                this.processObject(obj[key])
            } else if (typeof obj[key] === 'string' && obj[key].length) {
                if (this.hideFields.includes(key)) {
                    obj[key] = '**** hidden ****'; // Maybe incorrect solution, but it worked in 2.13.1
                }
            }
        }
    }

    public formatAttributes(
        attributes: UnformattedAttributes,
        additionalLogAttributes: LogAttributes
    ): LogItem {
        const {message, ...rest} = structuredClone(attributes);

        try {
            this.processObject(rest);
            this.processObject(additionalLogAttributes);
        } catch (e) {
        }

        const logItem = new LogItem({
            attributes: {
                message,
                ...rest,
            },
        })
        logItem.addAttributes(additionalLogAttributes);

        return logItem;
    }
}

(async () => {
    const logger = new Logger({
        logFormatter: new MyCompanyLogFormatter()
    })

    const lambdaHandler = async (event: Event) => {
        logger.info('==> Event in handler (secure)', {event});
        console.log('==> Event in handler (raw)', JSON.stringify(event));

        return {success: true}
    }

    const handler = middy()
        .use(injectLambdaContext(logger, {logEvent: true}))
        .handler(lambdaHandler)


    const rawEvent = {
        headers: {
            authorization: 'Bearer aaa.bbb.ccc',
            'content-type': 'application/json',
        }
    }

    // @ts-ignore
    await handler(rawEvent, {}, {});
})()

Steps to Reproduce

1. Run code with @aws-lambda-powertools/logger: 2.13.1
2. Receive response ==> Event in handler (raw) {"headers":{"authorization":"Bearer aaa.bbb.ccc","content-type":"application/json"}}
3. Run code with @aws-lambda-powertools/logger: 2.14.0
   4 Receive response ==> Event in handler (raw) {"headers":{"authorization":"**** hidden ****","content-type":"application/json"}}

Possible Solution

No response

Powertools for AWS Lambda (TypeScript) version

2.14.0

AWS Lambda function runtime

22.x

Packaging format used

npm

Execution logs

[dreamorosi]

Hi @VladimirGorobetsWildix, thank you for opening this issue.

The change of order of the fields has nothing to do with what you're observing. The change you're referring to was made in the in the default log formatter (here) which you're completely bypassing by providing your own custom log formatter (see logic that decides which one is used here).

The reason why you're seeing this behavior is that you're mutating directly the additionalLogAttributes object rather than working on a copy, like you're doing for the attributes one with structuredClone.

I would recommend changing the logic in your log formatter to something like this, which I confirmed works as intended:

class MyCompanyLogFormatter extends LogFormatter {
  private hideFields = ['authorization', 'password', 'secret', 'key', 'token'];

  processObject(obj: Record<string, any>) {
    for (const key in obj) {
      if (typeof obj[key] === 'object') {
        this.processObject(obj[key]);
      } else if (typeof obj[key] === 'string' && obj[key].length) {
        if (this.hideFields.includes(key)) {
          obj[key] = '**** hidden ****'; // Maybe incorrect solution, but it worked in 2.13.1
        }
      }
    }

    return obj; // return mutated object
  }

  public formatAttributes(
    attributes: UnformattedAttributes,
    additionalLogAttributes: LogAttributes
  ): LogItem {
    const { message, ...rest } = structuredClone(attributes);

    const logItem = new LogItem({
      attributes: {
        message,
      },
    });
    try {
      const sanitizedRest = this.processObject(rest);
      logItem.addAttributes(sanitizedRest);
    } catch {
      logItem.addAttributes(rest);
    }

    try {
      const sanitizedAdditional = this.processObject(
        structuredClone(additionalLogAttributes) // now it's a deep clone and can be mutated
      );
      logItem.addAttributes(sanitizedAdditional);
    } catch {
      logItem.addAttributes(additionalLogAttributes);
    }

    return logItem;
  }
}

I have tested the implementation above with the latest version and confirmed it logs as expected, and leaves the event unchanged:

{"message":"Lambda invocation event","logLevel":"INFO","timestamp":"2025-02-11T16:48:48.190Z","xRayTraceId":"1-67ab7f6f-722297141fd59b5c6ce6ed2e","awsRegion":"eu-west-1","serviceName":"service_undefined","sampleRateValue":0,"lambdaContext":{"invokedFunctionArn":"arn:aws:lambda:eu-west-1:123456789012:function:loggerorder-aamorosi-loggerOrderFunction-cefusswu","coldStart":true,"awsRequestId":"51f675cb-a01a-4afb-beb2-12ae229dbb81","memoryLimitInMB":"1024","functionName":"loggerorder-aamorosi-loggerOrderFunction-cefusswu","functionVersion":"$LATEST"},"event":{"headers":{"authorization":"**** hidden ****","content-type":"application/json"}}}
{"message":"==> Event in handler (secure)","logLevel":"INFO","timestamp":"2025-02-11T16:48:48.195Z","xRayTraceId":"1-67ab7f6f-722297141fd59b5c6ce6ed2e","awsRegion":"eu-west-1","serviceName":"service_undefined","sampleRateValue":0,"lambdaContext":{"invokedFunctionArn":"arn:aws:lambda:eu-west-1:123456789012:function:loggerorder-aamorosi-loggerOrderFunction-cefusswu","coldStart":true,"awsRequestId":"51f675cb-a01a-4afb-beb2-12ae229dbb81","memoryLimitInMB":"1024","functionName":"loggerorder-aamorosi-loggerOrderFunction-cefusswu","functionVersion":"$LATEST"},"event":{"headers":{"authorization":"**** hidden ****","content-type":"application/json"}}}
2025-02-11T16:48:48.196Z        51f675cb-a01a-4afb-beb2-12ae229dbb81    INFO    ==> Event in handler (raw) {"headers":{"authorization":"Bearer aaa.bbb.ccc","content-type":"application/json"}}

In the latest release we made some slight changes to how the attributes are handled internally to reduce object mutation and improve resource usage. Since they were internal changes we didn't include them in the release notes.

Likewise, I would not consider this a regression, since the contract between the Logger and LogFormatter class remained unchanged, and the parameters (aka the attributes) passed to the formatAttributes method are still the same / in the same order.

I will however open a PR to improve the documentation & examples around custom log formatters to advise customers to make a clone of these attributes if they intend to mutate them, rather than just rearrange/omit some of them.