chore(docs): miscellaneous updates and clarifications on docs (#2494)

* chore(docs): update banner in docs

* chore(docs): update layer arn & externalModules

* chore(docs): add eslint section to upgrade guide

* chore(docs): add testing your code section to metrics docs

---------

Co-authored-by: Alexander Schueren <sha@amazon.com>

docs/core/metrics.md

@@ -3,8 +3,6 @@ title: Metrics
 description: Core utility
 ---
 
-<!-- markdownlint-disable MD043 -->
-
 Metrics creates custom metrics asynchronously by logging metrics to standard output following [Amazon CloudWatch Embedded Metric Format (EMF)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html).
 
 These metrics can be visualized through [Amazon CloudWatch Console](https://console.aws.amazon.com/cloudwatch/).
@@ -460,3 +458,32 @@ CloudWatch EMF uses the same dimensions across all your metrics. Use `singleMetr
     ```
 
     1. Binding your handler method allows your handler to access `this` within the class methods.
+
+## Testing your code
+
+When unit testing your code that uses the `Metrics` utility, you may want to silence the logs emitted by the utility or assert that metrics are being emitted correctly. By default, the utility manages its own `console` instance, which means that you can't easily access or mock the logs emitted by the utility.
+
+To make it easier to test your code, you can set the `POWERTOOLS_DEV` environment variable to `true` to instruct the utility to use the global `console` object instead of its own.
+
+This allows you to spy on the logs emitted by the utility and assert that the metrics are being emitted correctly.
+
+```typescript title="Spying on emitted metrics"
+describe('Metrics tests', () => {
+  beforeAll(() => {
+    process.env.POWERTOOLS_DEV = 'true';
+  })
+
+  it('function metrics properly', async () => {
+    // Prepare
+    const metricsSpy = jest.spyOn(console, 'log').mockImplementation();
+
+    // Act & Assess
+  });
+});
+```
+
+When running your tests with both [Jest](https://jestjs.io) and [Vitest](http://vitest.dev), you can use the `--silent` flag to silence the logs emitted by the utility.
+
+```bash title="Disabling logs while testing"
+export POWERTOOLS_DEV=true && npx vitest --silent
+```

docs/index.md

@@ -89,7 +89,7 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa
                 const powertoolsLayer = LayerVersion.fromLayerVersionArn(
                   this,
                   'PowertoolsLayer',
-                  `arn:aws:lambda:${Stack.of(this).region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:3`
+                  `arn:aws:lambda:${Stack.of(this).region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:5`
                 );
                 
                 new Function(this, 'Function', {
@@ -103,7 +103,7 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa
             }
             ```
 
-            If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools` from being bundled since the packages will be already present the Layer:
+            If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools/*` and `@aws-sdk/*` from being bundled since the packages are already present the layer:
 
             ```typescript
             new NodejsFunction(this, 'Function', {
@@ -129,7 +129,7 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa
                     - !Sub arn:aws:lambda:${AWS::Region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:5
             ```
 
-            If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools` from being bundled since the packages will be already present the Layer:
+            If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools/*` and `@aws-sdk/*` from being bundled since the packages are already present the layer:
 
             ```yaml hl_lines="5-14"
             MyLambdaFunction:
@@ -142,10 +142,8 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa
                   BuildProperties:
                   Minify: true
                   External:
-                    - '@aws-lambda-powertools/commons'
-                    - '@aws-lambda-powertools/logger'
-                    - '@aws-lambda-powertools/metrics'
-                    - '@aws-lambda-powertools/tracer'
+                    - '@aws-lambda-powertools/*'
+                    - '@aws-sdk/*'
             ```
 
             Check the [documentation](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-build-typescript.html) for more details.
@@ -160,16 +158,14 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa
                   - arn:aws:lambda:${aws:region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:5
             ```
 
-            If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools` from being bundled since the packages will be already present the Layer:
+            If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools/*` and `@aws-sdk/*` from being bundled since the packages are already present the layer:
 
             ```yaml
             custom:
               esbuild:
                 external:
-                  - '@aws-lambda-powertools/commons'
-                  - '@aws-lambda-powertools/logger'
-                  - '@aws-lambda-powertools/metrics'
-                  - '@aws-lambda-powertools/tracer'
+                  - '@aws-lambda-powertools/*'
+                  - '@aws-sdk/*'
             ```
 
             Check the [documentation](https://floydspace.github.io/serverless-esbuild/) for more details.
@@ -193,7 +189,7 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa
               function_name = "lambda_function_name"
               role          = ...
               handler       = "index.handler"
-              runtime 		= "nodejs16.x"
+              runtime 		= "nodejs20.x"
               layers 		= ["arn:aws:lambda:{aws::region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:5"]
               source_code_hash = filebase64sha256("lambda_function_payload.zip")
             }
@@ -218,7 +214,7 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa
                 tracingConfig: {
                     mode: 'Active'
                 },
-                runtime: aws.lambda.Runtime.NodeJS16dX,
+                runtime: aws.lambda.Runtime.NodeJS20dX,
                 handler: 'index.handler',
                 role: role.arn,
                 architectures: ['x86_64']

docs/overrides/main.html

@@ -8,6 +8,6 @@
 {% endblock %}
 
 {% block announce %}
-Version 2 is generally available 🔥 Check out the <a href="{{ '../' ~ base_url ~ '/latest/upgrade' }}">upgrade guide</a> to see
-what's new.
+Starting from July 1, 2024 we will end support for Node.js 16. Learn more <a
+  href="https://github.com/aws-powertools/powertools-lambda-typescript/issues/2223" target="_blank">here</a>.
 {% endblock %}

docs/upgrade.md

@@ -173,6 +173,27 @@ In v2, you can now directly import from the `types` subpath export, e.g., `@aws-
     import { LogAttributes, UnformattedAttributes } from '@aws-lambda-powertools/logger/types';
     ```
 
+### Using eslint?
+
+When using `eslint`, you might need to use [`@typescript-eslint/parser`](https://github.com/typescript-eslint/typescript-eslint/tree/HEAD/packages/parser) and [`eslint-plugin-import`](https://www.npmjs.com/package/eslint-import-resolver-typescript) to resolve the new subpath imports.
+
+Below is an example of how to configure your `.eslintrc.json` file:
+
+```json
+{
+  "parser": "@typescript-eslint/parser",
+  "settings": {
+    "import/resolver": {
+      "node": {},
+      "typescript": {
+        "project": "./tsconfig.json",
+        "alwaysTryTypes": true,
+      },
+    },
+  },
+}
+```
+
 ## Logger
 
 ### Log sampling