docs(logger): add logEventIfEnabled() docs (#2924)

Co-authored-by: Leandro Damascena <[email protected]>

Author: dreamorosi

Diff for: 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 for: examples/snippets/logger/eventMiddy.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<void> {
-    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 for: examples/snippets/logger/eventDecorator.ts renamed to examples/snippets/logger/logEventDecorator.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 for: examples/snippets/logger/logEventManual.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 for: examples/snippets/logger/logEventMiddy.ts

@@ -0,0 +1,3 @@
+{
+  "foo": "bar"
+}

Diff for: examples/snippets/logger/samples/logEventInput.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"
+  }
+}

Diff for: examples/snippets/logger/samples/logEventOutput.json

@@ -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;