Merge branch 'main' into fix/tracer_fetch_pathname

Author: dreamorosi

.devcontainer/Dockerfile

@@ -1,5 +1,5 @@
 # See here for image contents: https://github.com/microsoft/vscode-dev-containers/blob/v0.212.0/containers/javascript-node/.devcontainer/base.Dockerfile
-FROM mcr.microsoft.com/vscode/devcontainers/javascript-node@sha256:e2228dfc5285942804c12b897f914e3262e9bba48c2ff473bad8b9fbd9bf7d26
+FROM mcr.microsoft.com/vscode/devcontainers/javascript-node@sha256:aedf26ccde02f734a8d8879778f5daac6c71609bb1df1b5a3e9d708f3c2827a2
 
 # Install fnm to manage Node.js versions
 RUN curl -fsSL https://fnm.vercel.app/install -o /tmp/install \

.github/dependabot.yml

@@ -44,7 +44,7 @@ updates:
         - "aws-sdk-client-mock-jest"
       aws-cdk:
         patterns:
-        - "@aws-cdk/*"
+        - "@aws-cdk/cli-lib-alpha"
         - "aws-cdk-lib"
         - "aws-cdk"
       typedoc:

.github/workflows/on_schedule_monthly_roadmap_reminder.yml

@@ -35,14 +35,14 @@ jobs:
           # repo_token: ${{ secrets.SCORECARD_TOKEN }}  # read-only fine-grained token to read branch protection settings
 
       - name: "Upload results"
-        uses: actions/upload-artifact@834a144ee995460fba8ed112a2fc961b36a5ec5a # v4.3.6
+        uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
         with:
           name: SARIF file
           path: results.sarif
           retention-days: 5
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@f0f3afee809481da311ca3a6ff1ff51d81dbeb24 # v3.26.4
+        uses: github/codeql-action/upload-sarif@4dd16135b69a43b6c8efb853346f8437d92d3c93 # v3.26.6
         with:
           sarif_file: results.sarif

.github/workflows/ossf_scorecard.yml

@@ -45,7 +45,7 @@ jobs:
       - name: Zip output
         run: zip -r cdk.out.zip layers/cdk.out
       - name: Archive CDK artifacts
-        uses: actions/upload-artifact@834a144ee995460fba8ed112a2fc961b36a5ec5a # v4.3.6
+        uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
         with:
           name: cdk-layer-artifact
           path: cdk.out.zip

.github/workflows/publish_layer.yml

@@ -53,7 +53,7 @@ jobs:
           script: |
             const script = require('.github/scripts/save_pr_details.js')
             await script({github, context, core})
-      - uses: actions/upload-artifact@834a144ee995460fba8ed112a2fc961b36a5ec5a # v4.3.6
+      - uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
         with:
           name: pr
           path: pr.txt

.github/workflows/record_pr.yml

@@ -93,7 +93,7 @@ jobs:
           cat cdk-layer-stack/${{ matrix.region }}-layer-version.txt
       - name: Save Layer ARN artifact
         if: ${{ inputs.stage == 'PROD' }}
-        uses: actions/upload-artifact@834a144ee995460fba8ed112a2fc961b36a5ec5a # v4.3.6
+        uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
         with:
           name: cdk-layer-stack-${{ matrix.region }}
           path: ./cdk-layer-stack/* # NOTE: upload-artifact does not inherit working-directory setting.

.github/workflows/reusable_deploy_layer_stack.yml

@@ -59,7 +59,7 @@ jobs:
       - name: Setup dependencies
         uses: aws-powertools/actions/.github/actions/cached-node-modules@d406bac5563f1d8c793519a3eedfe620f6a14872
       - name: Set up Python
-        uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f # v5.1.1
+        uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
         with:
           python-version: "3.12"
       - name: Install doc generation dependencies
@@ -96,7 +96,7 @@ jobs:
         run: |
           cp -r api site/
       - name: Create Artifact (Site)
-        uses: actions/upload-artifact@834a144ee995460fba8ed112a2fc961b36a5ec5a # v4.3.6
+        uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
         with:
           name: site
           path: site

.github/workflows/reusable_publish_docs.yml

@@ -32,6 +32,6 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332  # v4.1.7
       - name: Ensure 3rd party workflows have SHA pinned
-        uses: zgosalvez/github-actions-ensure-sha-pinned-actions@b88cd0aad2c36a63e42c71f81cb1958fed95ac87 # v3.0.10
+        uses: zgosalvez/github-actions-ensure-sha-pinned-actions@3c16e895bb662b4d7e284f032cbe8835a57773cc # v3.0.11
         with:
           allowlist: slsa-framework/slsa-github-generator

.github/workflows/secure-workflows.yml

@@ -9,12 +9,4 @@ layers/*/CHANGELOG.md
 # other files
 LICENSE
 .github/**
-**node_modules/** */
-# these will be removed from the ignore and linted in future PRs
-packages/batch/README.md
-packages/commons/README.md
-packages/jmespath/README.md
-packages/logger/README.md
-packages/metrics/README.md
-packages/parameters/README.md
-packages/tracer/README.md
+**node_modules/** */

.markdownlintignore

@@ -1,5 +1,5 @@
 # version 9.5.2
-FROM squidfunk/mkdocs-material@sha256:a73e4bbbccb09e5374cef28ebe68511c166222274f8486b25ad467ec1f5e8bbe
+FROM squidfunk/mkdocs-material@sha256:a2e3a31c00cfe1dd2dae83ba21dbfa2c04aee2fa2414275c230c27b91a4eda09
 
 COPY requirements.txt /tmp/
 RUN pip install --require-hashes -r /tmp/requirements.txt

docs/Dockerfile

@@ -542,6 +542,25 @@ We prioritise log level settings in this order:
 
 In the event you have set a log level in Powertools to a level that is lower than the ACL setting, we will output a warning log message informing you that your messages will be discarded by Lambda.
 
+### Reordering log keys position
+
+You can change the order of [standard Logger keys](#standard-structured-keys) or any keys that will be appended later at runtime via the `logRecordOrder` parameter.
+
+!!! note
+    This feature is available only in the default log formatter and not with custom log formatters.
+
+=== "reorderLogKeys.ts"
+
+    ```typescript hl_lines="5 10"
+    --8<-- "examples/snippets/logger/reorderLogKeys.ts"
+    ```
+
+=== "reorderLogKeysOutput.json"
+
+    ```json hl_lines="2-3"
+    --8<-- "examples/snippets/logger/reorderLogKeysOutput.json"
+    ```
+
 ### Setting timestamp to custom Timezone
 
 By default, Logger emits records with the default Lambda timestamp in **UTC**, i.e. `2016-06-20T12:08:10.000Z`

docs/core/logger.md

@@ -9,7 +9,7 @@
 
 {% block announce %}
 On September 1st, 2024 v1 of Powertools for AWS Lambda (TypeScript) <a
-  href="https://github.com/aws-powertools/powertools-lambda-typescript/issues/2224" target="_blank">will reach
+  href="https://github.com/aws-powertools/powertools-lambda-typescript/issues/2224" target="_blank">has reached
   End-of-Life</a>. We recommend you to <a href="https://docs.powertools.aws.dev/lambda/typescript/latest/upgrade/"
   target="_blank">upgrade to v2</a>.
 {% endblock %}

docs/overrides/main.html

@@ -1,4 +1,4 @@
 mike==1.1.2
-mkdocs-material==9.5.32
+mkdocs-material==9.5.34
 mkdocs-git-revision-date-plugin==0.3.2
 mkdocs-exclude==1.0.2

docs/requirements.in

@@ -235,9 +235,9 @@ mkdocs-get-deps==0.2.0 \
 mkdocs-git-revision-date-plugin==0.3.2 \
     --hash=sha256:2e67956cb01823dd2418e2833f3623dee8604cdf223bddd005fe36226a56f6ef
     # via -r requirements.in
-mkdocs-material==9.5.32 \
-    --hash=sha256:38ed66e6d6768dde4edde022554553e48b2db0d26d1320b19e2e2b9da0be1120 \
-    --hash=sha256:f3704f46b63d31b3cd35c0055a72280bed825786eccaf19c655b44e0cd2c6b3f
+mkdocs-material==9.5.34 \
+    --hash=sha256:1e60ddf716cfb5679dfd65900b8a25d277064ed82d9a53cd5190e3f894df7840 \
+    --hash=sha256:54caa8be708de2b75167fd4d3b9f3d949579294f49cb242515d4653dbee9227e
     # via -r requirements.in
 mkdocs-material-extensions==1.3.1 \
     --hash=sha256:10c9511cea88f568257f960358a467d12b970e1f7b2c0e5fb2bb48cab1928443 \

docs/requirements.txt

@@ -7,7 +7,7 @@ description: Guide to update between major Powertools for AWS Lambda (TypeScript
 
 ## End of support v1
 
-!!! warning "On March 13th, 2024, Powertools for AWS Lambda (TypeScript) v1 entered maintenance mode, and will reach end-of-life on September 1st, 2024. If you are still using v1, we strongly recommend you to read our upgrade guide and update to the latest version."
+!!! warning "On March 13th, 2024, Powertools for AWS Lambda (TypeScript) v1 entered maintenance mode, and has reached End-of-Life on September 1st, 2024. If you are still using v1, we strongly recommend you to upgrade to the latest version."
 
 Given our commitment to all of our customers using Powertools for AWS Lambda (TypeScript), we will keep npm v1 releases and documentation 1.x versions to prevent any disruption.
 

docs/upgrade.md

@@ -2,54 +2,61 @@
 
 This is a deployable CDK app that deploys AWS Lambda functions as part of a CloudFormation stack. These Lambda functions use the utilities made available as part of Powertools for AWS Lambda (TypeScript) to demonstrate their usage.
 
-> **Note**
-> You will need to have a valid AWS Account in order to deploy these resources. These resources may incur costs to your AWS Account. The cost from **some services** are covered by the [AWS Free Tier](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all) but not all of them. If you don't have an AWS Account follow [these instructions to create one](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/).
+> [!Warning]
+> You will need to have a valid AWS Account in order to deploy these resources. Many of the services in the example are covered [AWS Free Tier](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all) but you may incur charges if you exceed the free tier limits.
+If you don't have an AWS Account follow [these instructions to create one](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/).
 
 The example functions, located in the `functions` folder, are frontend by a REST API that is deployed using AWS API Gateway.
 
 The API has three endpoints:
 
- * `POST /` - Adds an item to the DynamoDB table
- * `GET /` - Retrieves all items from the DynamoDB table
- * `GET /{id}` - Retrieves a specific item from the DynamoDB table
+* `POST /` - Adds an item to the DynamoDB table
+* `GET /` - Retrieves all items from the DynamoDB table
+* `GET /{id}` - Retrieves a specific item from the DynamoDB table
 
 ## Deploying the stack
 
- * Navigate to this location of the repo in your terminal (`examples/cdk`)
- * `npm ci`
- * `npm run cdk deploy --all --profile <YOUR_AWS_PROFILE>`
+> [!Note]
+> The `examples/app` directory where this example is located is part of a monorepo. If you are interested in deploying the example only, follow the instructions below.
+> If instead you are working on the monorepo and want to deploy the example, follow the instructions in the [CONTRIBUTING](../../CONTRIBUTING.md#dev-setup) doc, then run `npm run cdk deploy -w examples/app` from the project's root.
 
-Note: Prior to deploying you may need to run `cdk bootstrap aws://<YOU_AWS_ACCOUNT_ID>/<AWS_REGION> --profile <YOUR_AWS_PROFILE>` if you have not already bootstrapped your account for CDK.
+If this is the first time you're using CDK in your AWS Account & AWS Region, you may need to run `npm run cdk bootstrap aws://<YOU_AWS_ACCOUNT_ID>/<AWS_REGION> --profile <YOUR_AWS_PROFILE>` to bootstrap your account for CDK.
 
-> **Note**
-> You can find your API Gateway Endpoint URL in the output values displayed after deployment.
+Then, still from within the `examples/app` directory, run the following commands:
+
+* `npm i --prefix ./` to install the dependencies
+* `npm run cdk deploy` and follow the prompts to deploy the stack
+
+When the deployment is complete, you will see the output values that include the API Gateway Endpoint URL.
 
 ## Execute the functions via API Gateway
 
 Use the API Gateway Endpoint URL from the output values to execute the functions. First, let's add two items to the DynamoDB Table by running:
 
 ```bash
-curl -XPOST --header 'Content-Type: application/json' --data '{"id":"myfirstitem","name":"Some Name for the first item"}' https://randomid12345.execute-api.eu-central-1.amazonaws.com/prod/
-curl -XPOST --header 'Content-Type: application/json' --data '{"id":"myseconditem","name":"Some Name for the second item"}' https://randomid1245.execute-api.eu-central-1.amazonaws.com/prod/
+curl -XPOST --header 'Content-Type: application/json' --data '{"id":"myfirstitem","name":"Some Name for the first item"}' https://<api-id>.execute-api.eu-central-1.amazonaws.com/prod/
+curl -XPOST --header 'Content-Type: application/json' --data '{"id":"myseconditem","name":"Some Name for the second item"}' https://<api-id>.execute-api.eu-central-1.amazonaws.com/prod/
 ````
 
 Now, let's retrieve all items by running:
 
 ```sh
-curl -XGET https://randomid12345.execute-api.eu-central-1.amazonaws.com/prod/
+curl -XGET https://<api-id>.execute-api.eu-central-1.amazonaws.com/prod/
 ```
 
 And finally, let's retrieve a specific item by running:
+
 ```bash
-curl -XGET https://randomid12345.execute-api.eu-central-1.amazonaws.com/prod/myseconditem/
+curl -XGET https://<api-id>.execute-api.eu-central-1.amazonaws.com/prod/myseconditem/
 ```
 
 ## Observe the outputs in AWS CloudWatch & X-Ray
 
 ### CloudWatch
 
 If we check the logs in CloudWatch, we can see that the logs are structured like this
-```
+
+```text
 2022-04-26T17:00:23.808Z	e8a51294-6c6a-414c-9777-6b0f24d8739b	DEBUG	
 {
     "level": "DEBUG",
@@ -62,10 +69,11 @@ If we check the logs in CloudWatch, we can see that the logs are structured like
 
 By having structured logs like this, we can easily search and analyse them in [CloudWatch Logs Insight](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html). Run the following query to get all messages for a specific `awsRequestId`:
 
-````
+````text
 filter awsRequestId="bcd50969-3a55-49b6-a997-91798b3f133a"
  | fields timestamp, message
 ````
+
 ### AWS X-Ray
 
 As we have enabled tracing for our Lambda-Funtions, you can visit [AWS CloudWatch Console](https://console.aws.amazon.com/cloudwatch/) and see [Traces](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-traces) and a [Service Map](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-using-xray-maps.html) for our application.
@@ -76,4 +84,4 @@ To delete the sample application that you created, run the command below while i
 
 ```bash
 cdk destroy
-```
+```

examples/app/README.md

@@ -1,3 +1,5 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { RemovalPolicy, Stack, type StackProps } from 'aws-cdk-lib';
 import { LambdaIntegration, RestApi } from 'aws-cdk-lib/aws-apigateway';
 import {
@@ -21,6 +23,12 @@ import { StringParameter } from 'aws-cdk-lib/aws-ssm';
 import type { Construct } from 'constructs';
 import { FunctionWithLogGroup } from './function-with-logstream-construct.js';
 
+// Get the current file URL
+const __filename = fileURLToPath(import.meta.url);
+
+// Get the current directory
+const __dirname = dirname(__filename);
+
 export class PowertoolsExampleStack extends Stack {
   public constructor(scope: Construct, id: string, props?: StackProps) {
     super(scope, id, props);
@@ -80,7 +88,7 @@ export class PowertoolsExampleStack extends Stack {
      * Because we are using ESM and tree shake, we create an optimized bundle.
      */
     const putItemFn = new FunctionWithLogGroup(this, 'put-item-fn', {
-      entry: './functions/put-item.ts',
+      entry: join(__dirname, '..', './functions/put-item.ts'),
       functionName: 'powertools-example-put-item',
       bundling: {
         minify: true,
@@ -124,7 +132,7 @@ export class PowertoolsExampleStack extends Stack {
      * in a centralized way across all your functions.
      */
     const getAllItemsFn = new FunctionWithLogGroup(this, 'get-all-items-fn', {
-      entry: './functions/get-all-items.ts',
+      entry: join(__dirname, '..', './functions/get-all-items.ts'),
       functionName: 'powertools-example-get-all-items',
       layers: [powertoolsLayer], // we use the powertools layer
       bundling: {
@@ -150,7 +158,7 @@ export class PowertoolsExampleStack extends Stack {
      * dependencies in it.
      */
     const getByIdFn = new FunctionWithLogGroup(this, 'get-by-id-fn', {
-      entry: './functions/get-by-id.ts',
+      entry: join(__dirname, '..', './functions/get-by-id.ts'),
       functionName: 'powertools-example-get-by-id',
       bundling: {
         minify: true,
@@ -172,7 +180,7 @@ export class PowertoolsExampleStack extends Stack {
       this,
       'process-items-stream-fn',
       {
-        entry: './functions/process-items-stream.ts',
+        entry: join(__dirname, '..', './functions/process-items-stream.ts'),
         functionName: 'powertools-example-process-items-stream',
         layers: [powertoolsLayer],
         bundling: {

examples/app/cdk/example-stack.ts

@@ -6,7 +6,7 @@ import type { DebugLogger } from '#types';
 /**
  * Scan the DynamoDB table and return all items.
  *
- * @note this function is purposefully not paginated to keep the example simple
+ * this function is purposefully not paginated to keep the example simple
  *
  * @param logger A logger instance
  */