docs(logger): middleware

Author: saragerion

docs/core/logger.md

@@ -70,23 +70,22 @@ Key | Example | Note
 
 You can enrich your structured logs with key Lambda context information in multiple ways.
 
-Method 1, using a class decorator:
+Method 1, using a [Middy](https://github.com/middyjs/middy) middleware:
 
 === "handler.ts"
 
-    ```typescript hl_lines="7"
+    ```typescript hl_lines="2 10-11"
     import { Logger } from "@aws-lambda-powertools/logger";
+    import { injectLambdaContext } from '@aws-lambda-powertools/logger/middleware/middy';
 
     const logger = new Logger();
-    
-    class Lambda {
-    
-        @logger.injectLambdaContext()
-        public handler() {
-            logger.info("This is an INFO log with some context");
-        }
 
-    }
+    const lambdaHandler = async () => {
+        logger.info("This is an INFO log with some context");
+    };
+
+    const handler = middy(lambdaHandler)
+        .use(injectLambdaContext(logger));
     ```
 
 Method 2, calling the `addContext` method:
@@ -107,6 +106,25 @@ Method 2, calling the `addContext` method:
     };
     ```
 
+Method 3, using a class decorator:
+
+=== "handler.ts"
+
+    ```typescript hl_lines="7"
+    import { Logger } from "@aws-lambda-powertools/logger";
+
+    const logger = new Logger();
+    
+    class Lambda {
+    
+        @logger.injectLambdaContext()
+        public handler() {
+            logger.info("This is an INFO log with some context");
+        }
+
+    }
+    ```
+
 In both case, the printed log will look like this:
 
 === "Example CloudWatch Logs excerpt"
@@ -116,7 +134,7 @@ In both case, the printed log will look like this:
         "cold_start": true,
         "function_arn": "arn:aws:lambda:eu-central-1:123456789012:function:shopping-cart-api-lambda-prod-eu-central-1",
         "function_memory_size": 128,
-        "function_request_id": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef",
+        "function_request_id": "c6af9ac6-7b61-11e6-9a41-93e812345678",
         "function_name": "shopping-cart-api-lambda-prod-eu-central-1",
         "level": "INFO",
         "message": "This is an INFO log with some context",
@@ -134,7 +152,7 @@ Key | Example
 **function_name** `string` | `shopping-cart-api-lambda-prod-eu-central-1`
 **function_memory_size**: `int` | `128`
 **function_arn**: `string` | `arn:aws:lambda:eu-central-1:123456789012:function:shopping-cart-api-lambda-prod-eu-central-1`
-**function_request_id**: `string` | `c6af9ac6-7b61-11e6-9a41-93e8deadbeef`
+**function_request_id**: `string` | `c6af9ac6-7b61-11e6-9a41-93e812345678`
 
 ### Appending persistent additional log keys and values
 
@@ -558,7 +576,7 @@ This is how the printed log would look:
             "service": "shopping-cart-api",
             "awsRegion": "eu-central-1",
             "correlationIds": {
-                "awsRequestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef",
+                "awsRequestId": "c6af9ac6-7b61-11e6-9a41-93e812345678",
                 "xRayTraceId": "abcdef123456abcdef123456abcdef123456",
                 "myCustomCorrelationId": "foo-bar-baz"
             },

packages/logger/README.md

@@ -10,6 +10,7 @@ npm run test
 npm run example:hello-world
 npm run example:inject-context
 npm run example:inject-context-decorator
+npm run example:inject-context-middleware
 npm run example:errors
 npm run example:constructor-options
 npm run example:custom-log-formatter
@@ -70,19 +71,19 @@ logger.error('This is an ERROR log');
 
 ### Capturing Lambda context info
 
-Without decorators:
+With the middy middleware `injectLambdaContext`:
 
 ```typescript
 // Environment variables set for the Lambda
 process.env.LOG_LEVEL = 'INFO';
 process.env.POWERTOOLS_SERVICE_NAME = 'hello-world';
+import { injectLambdaContext } from '../src/middleware/middy';
+import middy from '@middy/core';
 
 const logger = new Logger();
 
 const lambdaHandler: Handler = async () => {
 
-  logger.addContext(context);
-
   logger.info('This is an INFO log');
 
   return {
@@ -91,6 +92,9 @@ const lambdaHandler: Handler = async () => {
 
 };
 
+const handlerWithMiddleware = middy(lambdaHandler)
+  .use(injectLambdaContext(logger));
+
 ```
 
 <details>
@@ -99,7 +103,7 @@ const lambdaHandler: Handler = async () => {
 ```bash
 
 {
-  aws_request_id: 'c6af9ac6-7b61-11e6-9a41-93e8deadbeef',
+  aws_request_id: 'c6af9ac6-7b61-11e6-9a41-93e812345678',
   cold_start: true,
   lambda_function_arn: 'arn:aws:lambda:eu-central-1:123456789012:function:Example',
   lambda_function_memory_size: 128,
@@ -111,7 +115,7 @@ const lambdaHandler: Handler = async () => {
   xray_trace_id: 'abcdef123456abcdef123456abcdef123456'
 }
 {
-  aws_request_id: 'c6af9ac6-7b61-11e6-9a41-93e8deadbeef',
+  aws_request_id: 'c6af9ac6-7b61-11e6-9a41-93e812345678',
   cold_start: true,
   lambda_function_arn: 'arn:aws:lambda:eu-central-1:123456789012:function:Example',
   lambda_function_memory_size: 128,
@@ -126,6 +130,50 @@ const lambdaHandler: Handler = async () => {
 ```
 </details>
 
+With the `addContext` method:
+
+```typescript
+// Environment variables set for the Lambda
+process.env.LOG_LEVEL = 'INFO';
+process.env.POWERTOOLS_SERVICE_NAME = 'hello-world';
+
+const logger = new Logger();
+
+const lambdaHandler: Handler = async () => {
+
+  logger.addContext(context);
+
+  logger.info('This is an INFO log');
+
+  return {
+    foo: 'bar'
+  };
+
+};
+
+```
+
+<details>
+ <summary>Click to expand and see the logs outputs</summary>
+
+```bash
+
+{
+  cold_start: true,
+  function_arn: 'arn:aws:lambda:eu-central-1:123456789012:function:foo-bar-function',
+  function_memory_size: 128,
+  function_request_id: 'c6af9ac6-7b61-11e6-9a41-93e812345678',
+  function_name: 'foo-bar-function',
+  level: 'INFO',
+  message: 'This is an INFO log',
+  service: 'hello-world',
+  timestamp: '2021-12-15T23:56:17.773Z',
+  xray_trace_id: 'abcdef123456abcdef123456abcdef123456'
+}
+
+```
+</details>
+
 
 With decorators:
 
@@ -157,15 +205,15 @@ new Lambda().handler(dummyEvent, dummyContext, () => console.log('Lambda invoked
 ```bash
 
 {
-  aws_request_id: 'c6af9ac6-7b61-11e6-9a41-93e8deadbeef',
   cold_start: true,
-  lambda_function_arn: 'arn:aws:lambda:eu-central-1:123456789012:function:Example',
-  lambda_function_memory_size: 128,
-  lambda_function_name: 'foo-bar-function',
+  function_arn: 'arn:aws:lambda:eu-central-1:123456789012:function:foo-bar-function',
+  function_memory_size: 128,
+  function_request_id: 'c6af9ac6-7b61-11e6-9a41-93e812345678',
+  function_name: 'foo-bar-function',
   level: 'INFO',
   message: 'This is an INFO log with some context',
   service: 'hello-world',
-  timestamp: '2021-03-25T11:00:01.400Z',
+  timestamp: '2021-12-15T23:57:25.749Z',
   xray_trace_id: 'abcdef123456abcdef123456abcdef123456'
 }
 
@@ -536,7 +584,7 @@ const lambdaHandler: Handler = async (event, context) => {
   service: 'hello-world',
   awsRegion: 'eu-central-1',
   correlationIds: {
-    awsRequestId: 'c6af9ac6-7b61-11e6-9a41-93e8deadbeef',
+    awsRequestId: 'c6af9ac6-7b61-11e6-9a41-93e812345678',
     xRayTraceId: 'abcdef123456abcdef123456abcdef123456',
     myCustomCorrelationId: 'foo-bar-baz'
   },

packages/logger/examples/inject-context-middleware.ts

@@ -5,26 +5,27 @@ require('./../tests/helpers/populateEnvironmentVariables');
 process.env.LOG_LEVEL = 'INFO';
 process.env.POWERTOOLS_SERVICE_NAME = 'hello-world';
 
+import * as dummyEvent from '../../../tests/resources/events/custom/hello-world.json';
 import { Handler } from 'aws-lambda';
 import { Logger } from '../src';
+import { context as dummyContext } from '../../../tests/resources/contexts/hello-world';
 import { injectLambdaContext } from '../src/middleware/middy';
 import middy from '@middy/core';
 
 const logger = new Logger();
 
 const lambdaHandler: Handler = async () => {
 
-  logger.debug('This is a DEBUG log');
   logger.info('This is an INFO log');
-  logger.warn('This is a WARN log');
-  logger.error('This is an ERROR log');
 
   return {
     foo: 'bar'
   };
 
 };
 
-const lambdaHandlerWithMiddleware = middy(lambdaHandler)
+const handlerWithMiddleware = middy(lambdaHandler)
   .use(injectLambdaContext(logger));
 
+handlerWithMiddleware(dummyEvent, dummyContext, () => console.log('Lambda invoked!'));
+