diff --git a/docs/core/logger.md b/docs/core/logger.md index 8a8408c121..74be0bfde3 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -160,26 +160,48 @@ In each case, the printed log will look like this: ### Log incoming event -When debugging in non-production environments, you can instruct Logger to log the incoming event with the middleware/decorator parameter `logEvent`. +When debugging in non-production environments, you can log the incoming event using the `logEventIfEnabled()` method or by setting the `logEvent` option in the `injectLambdaContext()` Middy.js middleware or class method decorator. ???+ warning This is disabled by default to prevent sensitive info being logged -=== "Middy Middleware" +=== "`logEventIfEnabled()`" + + ```typescript hl_lines="1 8" + --8<-- "examples/snippets/logger/logEventManual.ts" + ``` + + 1. You can control the event logging via the `POWERTOOLS_LOGGER_LOG_EVENT` environment variable. - ```typescript hl_lines="15" - --8<-- "examples/snippets/logger/eventMiddy.ts" +=== "Middy.js Middleware" + + ```typescript hl_lines="10" + --8<-- "examples/snippets/logger/logEventMiddy.ts" ``` + 1. The `logEvent` option takes precedence over the `POWERTOOLS_LOGGER_LOG_EVENT` environment variable. + === "Decorator" - ```typescript hl_lines="8" - --8<-- "examples/snippets/logger/eventDecorator.ts" + ```typescript hl_lines="7" + --8<-- "examples/snippets/logger/logEventDecorator.ts" ``` - 1. Binding your handler method allows your handler to access `this` within the class methods. + 1. The `logEvent` option takes precedence over the `POWERTOOLS_LOGGER_LOG_EVENT` environment variable. + +=== "payload.json" + + ```json + --8<-- "examples/snippets/logger/samples/logEventInput.json" + ``` + +=== "CloudWatch output" + + ```json hl_lines="8 13-15" + --8<-- "examples/snippets/logger/samples/logEventOutput.json" + ``` -Use `POWERTOOLS_LOGGER_LOG_EVENT` environment variable to enable or disable (`true`/`false`) this feature. +Use `POWERTOOLS_LOGGER_LOG_EVENT` environment variable to enable or disable (`true`/`false`) this feature. When using Middy.js middleware or class method decorator, the `logEvent` option will take precedence over the environment variable. ### Appending additional keys diff --git a/examples/snippets/logger/eventMiddy.ts b/examples/snippets/logger/eventMiddy.ts deleted file mode 100644 index 3c3a40596b..0000000000 --- a/examples/snippets/logger/eventMiddy.ts +++ /dev/null @@ -1,16 +0,0 @@ -import { Logger } from '@aws-lambda-powertools/logger'; -import { injectLambdaContext } from '@aws-lambda-powertools/logger/middleware'; -import middy from '@middy/core'; - -const logger = new Logger(); - -const lambdaHandler = async ( - _event: unknown, - _context: unknown -): Promise => { - logger.info('This is an INFO log with some context'); -}; - -export const handler = middy(lambdaHandler).use( - injectLambdaContext(logger, { logEvent: true }) -); diff --git a/examples/snippets/logger/eventDecorator.ts b/examples/snippets/logger/logEventDecorator.ts similarity index 60% rename from examples/snippets/logger/eventDecorator.ts rename to examples/snippets/logger/logEventDecorator.ts index ab8feae23a..8e5e325ed7 100644 --- a/examples/snippets/logger/eventDecorator.ts +++ b/examples/snippets/logger/logEventDecorator.ts @@ -4,12 +4,11 @@ import { Logger } from '@aws-lambda-powertools/logger'; const logger = new Logger(); class Lambda implements LambdaInterface { - // Set the log event flag to true - @logger.injectLambdaContext({ logEvent: true }) + @logger.injectLambdaContext({ logEvent: true }) // (1) public async handler(_event: unknown, _context: unknown): Promise { - logger.info('This is an INFO log with some context'); + // ... your logic here } } const myFunction = new Lambda(); -export const handler = myFunction.handler.bind(myFunction); // (1) +export const handler = myFunction.handler.bind(myFunction); diff --git a/examples/snippets/logger/logEventManual.ts b/examples/snippets/logger/logEventManual.ts new file mode 100644 index 0000000000..76c0d3a941 --- /dev/null +++ b/examples/snippets/logger/logEventManual.ts @@ -0,0 +1,10 @@ +process.env.POWERTOOLS_LOGGER_LOG_EVENT = 'true'; + +import { Logger } from '@aws-lambda-powertools/logger'; + +const logger = new Logger(); + +export const handler = async (event: unknown) => { + logger.logEventIfEnabled(event); // (1) + // ... your logic here +}; diff --git a/examples/snippets/logger/logEventMiddy.ts b/examples/snippets/logger/logEventMiddy.ts new file mode 100644 index 0000000000..2263868a53 --- /dev/null +++ b/examples/snippets/logger/logEventMiddy.ts @@ -0,0 +1,11 @@ +import { Logger } from '@aws-lambda-powertools/logger'; +import { injectLambdaContext } from '@aws-lambda-powertools/logger/middleware'; +import middy from '@middy/core'; + +const logger = new Logger(); + +export const handler = middy(async () => { + // ... your logic here +}).use( + injectLambdaContext(logger, { logEvent: true }) // (1) +); diff --git a/examples/snippets/logger/samples/logEventInput.json b/examples/snippets/logger/samples/logEventInput.json new file mode 100644 index 0000000000..b42f309e7a --- /dev/null +++ b/examples/snippets/logger/samples/logEventInput.json @@ -0,0 +1,3 @@ +{ + "foo": "bar" +} \ No newline at end of file diff --git a/examples/snippets/logger/samples/logEventOutput.json b/examples/snippets/logger/samples/logEventOutput.json new file mode 100644 index 0000000000..31c76da475 --- /dev/null +++ b/examples/snippets/logger/samples/logEventOutput.json @@ -0,0 +1,16 @@ +{ + "cold_start": true, + "function_arn": "arn:aws:lambda:eu-west-1:123456789012:function:LogEventFn", + "function_memory_size": "128", + "function_name": "LogEventFn", + "function_request_id": "0a9df60d-e2de-447d-ba3e-45f149eae6c9", + "level": "INFO", + "message": "Lambda invocation event", + "sampling_rate": 0, + "service": "service_undefined", + "timestamp": "2024-08-14T10:08:06.199Z", + "xray_trace_id": "1-66bc8205-21f8b5190da519d22b2b0533", + "event": { + "foo": "bar" + } +} \ No newline at end of file diff --git a/packages/logger/src/Logger.ts b/packages/logger/src/Logger.ts index 48510a15d1..90277d744f 100644 --- a/packages/logger/src/Logger.ts +++ b/packages/logger/src/Logger.ts @@ -498,11 +498,24 @@ class Logger extends Utility implements LoggerInterface { } /** - * Logs a Lambda invocation event, if it *should*. + * Log the AWS Lambda event payload for the current invocation if the environment variable `POWERTOOLS_LOG_EVENT` is set to `true`. * - ** @param {unknown} event - * @param {boolean} [overwriteValue] - * @returns {void} + * @example + * ```ts + * process.env.POWERTOOLS_LOG_EVENT = 'true'; + * + * import { Logger } from '@aws-lambda-powertools/logger'; + * + * const logger = new Logger(); + * + * export const handler = async (event) => { + * logger.logEventIfEnabled(event); + * // ... your handler code + * } + * ``` + * + * @param {unknown} event - The AWS Lambda event payload. + * @param {boolean} overwriteValue - Overwrite the environment variable value. */ public logEventIfEnabled(event: unknown, overwriteValue?: boolean): void { if (!this.shouldLogEvent(overwriteValue)) return;