docs: formatting fixes and improvements

Author: saragerion

docs/Dockerfile

@@ -1,2 +1,2 @@
 FROM squidfunk/mkdocs-material
-RUN pip install mkdocs-git-revision-date-plugin
+RUN pip install mkdocs-git-revision-date-plugin mkdocs-glightbox

docs/core/logger.md

@@ -13,6 +13,13 @@ Logger provides an opinionated logger with output structured as JSON.
 * Appending additional keys to structured logs at any point in time.
 * Providing a custom log formatter (Bring Your Own Formatter) to output logs in a structure compatible with your organization’s Logging RFC.
 
+<br />
+
+<figure>
+  <img src="../../media/logger_utility_showcase.png" loading="lazy" />
+  <figcaption>Logger showcase - Log attributes</figcaption>
+</figure>
+
 ## Getting started
 
 ### Installation
@@ -25,7 +32,7 @@ npm install @aws-lambda-powertools/logger
 
 ### Usage
 
-The `Logger` utility must always be instantiated outside of the Lambda handler. In doing this, subsequent invocations processed by the same instance of your function can reuse these resources. This saves cost by reducing function run time. In addition, `Logger` can keep track of a cold start and inject the appropriate fields into logs.
+The `Logger` utility must always be instantiated outside the Lambda handler. By doing this, subsequent invocations processed by the same instance of your function can reuse these resources. This saves cost by reducing function run time. In addition, `Logger` can keep track of a cold start and inject the appropriate fields into logs.
 
 === "handler.ts"
 
@@ -45,10 +52,10 @@ The library requires two settings. You can set them as environment variables, or
 
 These settings will be used across all logs emitted:
 
-Setting | Description                                                                                                      | Environment variable | Constructor parameter
-------------------------------------------------- |------------------------------------------------------------------------------------------------------------------| ------------------------------------------------- | -------------------------------------------------
-**Logging level** | Sets how verbose Logger should be (INFO, by default). Supported values are: `DEBUG`, `INFO`, `WARN`, `ERROR`     |  `LOG_LEVEL` | `logLevel`
-**Service name** | Sets the name of service of which the Lambda function is part of, that will be present across all log statements | `POWERTOOLS_SERVICE_NAME` | `serviceName`
+| Setting           | Description                                                                                                      | Environment variable      | Constructor parameter |
+|-------------------|------------------------------------------------------------------------------------------------------------------|---------------------------|-----------------------|
+| **Logging level** | Sets how verbose Logger should be (INFO, by default). Supported values are: `DEBUG`, `INFO`, `WARN`, `ERROR`     | `LOG_LEVEL`               | `logLevel`            |
+| **Service name**  | Sets the name of service of which the Lambda function is part of, that will be present across all log statements | `POWERTOOLS_SERVICE_NAME` | `serviceName`         |
 
 For a **complete list** of supported environment variables, refer to [this section](./../index.md#environment-variables).
 
@@ -87,15 +94,15 @@ For a **complete list** of supported environment variables, refer to [this secti
 
 Your Logger will include the following keys to your structured logging (default log formatter):
 
-Key | Example | Note
-------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------
-**level**: `string` | `INFO` | Logging level set for the Lambda function"s invocation
-**message**: `string` | `Query performed to DynamoDB` | A descriptive, human-readable representation of this log item
-**sampling_rate**: `float` |  `0.1` | When enabled, it prints all the logs of a percentage of invocations, e.g. 10%
-**service**: `string` | `serverlessAirline` | A unique name identifier of the service this Lambda function belongs to, by default `service_undefined`
-**timestamp**: `string` | `2011-10-05T14:48:00.000Z` | Timestamp string in simplified extended ISO format (ISO 8601)
-**xray_trace_id**: `string` | `1-5759e988-bd862e3fe1be46a994272793` | X-Ray Trace ID. This value is always presented in Lambda environment, whether [tracing is enabled](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html){target="_blank"} or not. Logger will always log this value.
-**error**: `Object` | `{ name: "Error", location: "/my-project/handler.ts:18", message: "Unexpected error #1", stack: "[stacktrace]"}` | Optional - An object containing information about the Error passed to the logger
+| Key                         | Example                                                                                                          | Note                                                                                                                                                                                                                            |
+|-----------------------------|------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **level**: `string`         | `INFO`                                                                                                           | Logging level set for the Lambda function"s invocation                                                                                                                                                                          |
+| **message**: `string`       | `Query performed to DynamoDB`                                                                                    | A descriptive, human-readable representation of this log item                                                                                                                                                                   |
+| **sampling_rate**: `float`  | `0.1`                                                                                                            | When enabled, it prints all the logs of a percentage of invocations, e.g. 10%                                                                                                                                                   |
+| **service**: `string`       | `serverlessAirline`                                                                                              | A unique name identifier of the service this Lambda function belongs to, by default `service_undefined`                                                                                                                         |
+| **timestamp**: `string`     | `2011-10-05T14:48:00.000Z`                                                                                       | Timestamp string in simplified extended ISO format (ISO 8601)                                                                                                                                                                   |
+| **xray_trace_id**: `string` | `1-5759e988-bd862e3fe1be46a994272793`                                                                            | X-Ray Trace ID. This value is always presented in Lambda environment, whether [tracing is enabled](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html){target="_blank"} or not. Logger will always log this value. |
+| **error**: `Object`         | `{ name: "Error", location: "/my-project/handler.ts:18", message: "Unexpected error #1", stack: "[stacktrace]"}` | Optional - An object containing information about the Error passed to the logger                                                                                                                                                |
 
 ### Capturing Lambda context info
 
@@ -111,27 +118,11 @@ Key | Example
 **function_arn**: `string` | `arn:aws:lambda:eu-west-1:123456789012:function:shopping-cart-api-lambda-prod-eu-west-1`
 **function_request_id**: `string` | `c6af9ac6-7b61-11e6-9a41-93e812345678`
 
-=== "Manual"
-
-    ```typescript hl_lines="7"
-    import { Logger } from '@aws-lambda-powertools/logger';
-
-    const logger = new Logger();
-
-    export const handler = async (_event, context): Promise<void> => {
-    
-        logger.addContext(context);
-        
-        logger.info('This is an INFO log with some context');
-
-    };
-    ```
-
 === "Middy Middleware"
 
     !!! tip "Using Middy for the first time?"
         You can install Middy by running `npm i @middy/core`.
-        Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}.
+        Learn more about [its usage and lifecycle in the official Middy documentation](https://middy.js.org/docs/intro/getting-started){target="_blank"}.
 
     ```typescript hl_lines="1-2 10-11"
     import { Logger, injectLambdaContext } from '@aws-lambda-powertools/logger';
@@ -167,6 +158,21 @@ Key | Example
     export const myFunction = new Lambda();
     export const handler = myFunction.handler;
     ```
+=== "Manual"
+
+    ```typescript hl_lines="7"
+    import { Logger } from '@aws-lambda-powertools/logger';
+
+    const logger = new Logger();
+
+    export const handler = async (_event, context): Promise<void> => {
+    
+        logger.addContext(context);
+        
+        logger.info('This is an INFO log with some context');
+
+    };
+    ```
 
 In each case, the printed log will look like this:
 
@@ -189,7 +195,7 @@ 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` or via POWERTOOLS_LOGGER_LOG_EVENT env var set to `true`.
+When debugging in non-production environments, you can instruct Logger to log the incoming event with the middleware/decorator parameter `logEvent` or via `POWERTOOLS_LOGGER_LOG_EVENT` env var set to `true`.
 
 ???+ warning
 This is disabled by default to prevent sensitive info being logged

docs/core/metrics.md

@@ -14,6 +14,13 @@ These metrics can be visualized through [Amazon CloudWatch Console](https://cons
 * Metrics are created asynchronously by the CloudWatch service. You do not need any custom stacks, and there is no impact to Lambda function latency.
 * Creating a one-off metric with different dimensions.
 
+<br />
+
+<figure>
+  <img src="../../media/metrics_utility_showcase.png" loading="lazy" />
+  <figcaption>Metrics showcase - Handler Annotations</figcaption>
+</figure>
+
 ## Terminologies
 
 If you're new to Amazon CloudWatch, there are two terminologies you must be aware of before using this utility:
@@ -26,6 +33,7 @@ If you're new to Amazon CloudWatch, there are two terminologies you must be awar
   <figcaption>Metric terminology, visually explained</figcaption>
 </figure>
 
+
 ## Getting started
 
 ### Installation
@@ -58,10 +66,10 @@ The library requires two settings. You can set them as environment variables, or
 
 These settings will be used across all metrics emitted:
 
-Setting | Description | Environment variable | Constructor parameter
-------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------
-**Metric namespace** | Logical container where all metrics will be placed e.g. `serverlessAirline` |  `POWERTOOLS_METRICS_NAMESPACE` | `namespace`
-**Service** | Optionally, sets **service** metric dimension across all metrics e.g. `payment` | `POWERTOOLS_SERVICE_NAME` | `serviceName`
+| Setting              | Description                                                                     | Environment variable           | Constructor parameter |
+|----------------------|---------------------------------------------------------------------------------|--------------------------------|-----------------------|
+| **Metric namespace** | Logical container where all metrics will be placed e.g. `serverlessAirline`     | `POWERTOOLS_METRICS_NAMESPACE` | `namespace`           |
+| **Service**          | Optionally, sets **service** metric dimension across all metrics e.g. `payment` | `POWERTOOLS_SERVICE_NAME`      | `serviceName`         |
 
 For a **complete list** of supported environment variables, refer to [this section](./../index.md#environment-variables).
 
@@ -221,7 +229,7 @@ You can add default dimensions to your metrics by passing them as parameters in
 
     !!! tip "Using Middy for the first time?"
         You can install Middy by running `npm i @middy/core`.
-        Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}.
+        Learn more about [its usage and lifecycle in the official Middy documentation](https://middy.js.org/docs/intro/getting-started){target="_blank"}.
 
     ```typescript hl_lines="1-2 11 13"
     import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics';
@@ -292,24 +300,24 @@ If you do not use the middleware or decorator, you have to flush your metrics ma
     * Namespace is set only once (or none)
     * Metric units must be [supported by CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html)
 
-#### Manually
-
-You can manually flush the metrics with `publishStoredMetrics` as follows:
+#### Middy middleware
 
-!!! warning
-    Metrics, dimensions and namespace validation still applies.
+See below an example of how to automatically flush metrics with the Middy-compatible `logMetrics` middleware.
 
 === "handler.ts"
 
-    ```typescript hl_lines="7"
-    import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
+    ```typescript hl_lines="1-2 7 10-11"
+    import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics';
+    import middy from '@middy/core';
 
     const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });
 
-    export const handler = async (_event: any, _context: any): Promise<void> => {
-        metrics.addMetric('successfulBooking', MetricUnits.Count, 10);
-        metrics.publishStoredMetrics();
+    const lambdaHandler = async (_event: any, _context: any): Promise<void> => {
+        metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
     };
+
+    export const handler = middy(lambdaHandler)
+        .use(logMetrics(metrics));
     ```
 
 === "Example CloudWatch Logs excerpt"
@@ -321,7 +329,7 @@ You can manually flush the metrics with `publishStoredMetrics` as follows:
         "Timestamp": 1592234975665,
         "CloudWatchMetrics": [
             {
-            "Namespace": "successfulBooking",
+            "Namespace": "serverlessAirline",
             "Dimensions": [
                 [
                 "service"
@@ -333,31 +341,34 @@ You can manually flush the metrics with `publishStoredMetrics` as follows:
                 "Unit": "Count"
                 }
             ]
-            }
-        ]
         },
         "service": "orders"
     }
     ```
 
-#### Middy middleware
+#### Using the class decorator
 
-See below an example of how to automatically flush metrics with the Middy-compatible `logMetrics` middleware.
+!!! info
+    Decorators can only be attached to a class declaration, method, accessor, property, or parameter. Therefore, if you prefer to write your handler as a standard function rather than a Class method, check the [middleware](#using-a-middleware) or [manual](#manually) method sections instead.  
+    See the [official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/decorators.html) for more details.
+
+The `logMetrics` decorator of the metrics utility can be used when your Lambda handler function is implemented as method of a Class.
 
 === "handler.ts"
 
-    ```typescript hl_lines="1-2 7 10-11"
-    import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics';
-    import middy from '@middy/core';
+    ```typescript hl_lines="8"
+    import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
+    import { LambdaInterface } from '@aws-lambda-powertools/commons';
 
     const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });
 
-    const lambdaHandler = async (_event: any, _context: any): Promise<void> => {
-        metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
-    };
+    export class MyFunction implements LambdaInterface {
 
-    export const handler = middy(lambdaHandler)
-        .use(logMetrics(metrics));
+        @metrics.logMetrics()
+        public async handler(_event: any, _context: any): Promise<void> {
+            metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
+        }
+    }
     ```
 
 === "Example CloudWatch Logs excerpt"
@@ -369,7 +380,7 @@ See below an example of how to automatically flush metrics with the Middy-compat
         "Timestamp": 1592234975665,
         "CloudWatchMetrics": [
             {
-            "Namespace": "serverlessAirline",
+            "Namespace": "successfulBooking",
             "Dimensions": [
                 [
                 "service"
@@ -386,29 +397,24 @@ See below an example of how to automatically flush metrics with the Middy-compat
     }
     ```
 
-#### Using the class decorator
+#### Manually
 
-!!! info
-    Decorators can only be attached to a class declaration, method, accessor, property, or parameter. Therefore, if you prefer to write your handler as a standard function rather than a Class method, check the [middleware](#using-a-middleware) or [manual](#manually) method sections instead.  
-    See the [official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/decorators.html) for more details.
+You can manually flush the metrics with `publishStoredMetrics` as follows:
 
-The `logMetrics` decorator of the metrics utility can be used when your Lambda handler function is implemented as method of a Class.
+!!! warning
+Metrics, dimensions and namespace validation still applies.
 
 === "handler.ts"
 
-    ```typescript hl_lines="8"
+    ```typescript hl_lines="7"
     import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
-    import { LambdaInterface } from '@aws-lambda-powertools/commons';
 
     const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });
 
-    export class MyFunction implements LambdaInterface {
-
-        @metrics.logMetrics()
-        public async handler(_event: any, _context: any): Promise<void> {
-            metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
-        }
-    }
+    export const handler = async (_event: any, _context: any): Promise<void> => {
+        metrics.addMetric('successfulBooking', MetricUnits.Count, 10);
+        metrics.publishStoredMetrics();
+    };
     ```
 
 === "Example CloudWatch Logs excerpt"
@@ -432,6 +438,8 @@ The `logMetrics` decorator of the metrics utility can be used when your Lambda h
                 "Unit": "Count"
                 }
             ]
+            }
+        ]
         },
         "service": "orders"
     }