Merge branch 'main' into support_crac_on_powertools_metrics

Author: subhash686

.github/workflows/build-docs.yml

@@ -1,7 +1,7 @@
-# Build Docs
+# Build Latest Docs
 #
 # Description:
-#   Builds the docs and stores them in S3 to be served by our docs platform
+#   Builds the latest docs and stores them in S3 to be served by our docs platform
 #
 #   The workflow allows us to build to the main location (/lambda/java/) and to an alias
 #   (i.e. /lambda/java/preview/) if needed
@@ -15,17 +15,13 @@
 on:
   workflow_dispatch:
     inputs:
-      alias:
+      version:
+        description: "Version to build and publish docs (1.28.0, develop)"
+        required: true
         type: string
-        required: false
-        description: |
-          Alias to deploy the documentation into, this is mostly for testing pre-release
-          versions of the documentation, such as beta versions or snapshots.
 
-          https://docs.powertools.aws.dev/lambda/java/<alias>
-
-name: Build Docs
-run-name: Build Docs - ${{ contains(github.head_ref, 'main') && 'main' || inputs.alias }}
+name: Build Latest Docs
+run-name: Build Latest Docs - ${{ inputs.version }}
 
 jobs:
   docs:
@@ -35,28 +31,58 @@ jobs:
       id-token: write
     environment: Docs
     steps:
-      - name: Sanity Check
-        if: ${{ github.head_ref != 'main' || inputs.alias == '' }}
-        run:
-          echo "::error::No buildable docs"
-
       - name: Checkout Repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-        with: 
+        with:
           fetch-depth: 0
       - name: Build
         run: |
           mkdir -p dist
           docker build -t squidfunk/mkdocs-material ./docs/
           docker run --rm -t -v ${PWD}:/docs squidfunk/mkdocs-material build
-          cp -R site/* dist/
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@ececac1a45f3b08a01d2dd070d28d111c5fe6722
         with:
           aws-region: us-east-1
           role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }}
-      - name: Deploy
+      - name: Deploy Docs (Version)
+        env:
+          VERSION: ${{ inputs.version }}
+          ALIAS: "latest"
         run: |
           aws s3 sync \
-            dist \
-            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ github.head_ref == 'main' && '' || format('{0}/', inputs.alias )}}
+            site/ \
+            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.VERSION }}/
+      - name: Deploy Docs (Alias)
+        env:
+          VERSION: ${{ inputs.version }}
+          ALIAS: "latest"
+        run: |
+          aws s3 sync \
+            site/ \
+            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.ALIAS }}/
+      - name: Deploy Docs (Version JSON)
+        env:
+          VERSION: ${{ inputs.version }}
+          ALIAS: "latest"
+        # We originally used "mike" from PyPi to manage versions for us, but since we moved to S3, we can't use it to manage versions any more.
+        # Instead, we're using some shell script that manages the versions.
+        #
+        # Operations:
+        #   1. Download the versions.json file from S3
+        #   2. Find any reference to the alias and delete it from the versions file
+        #   3. This is voodoo (don't use JQ):
+        #      - we assign the input as $o and the new version/alias as $n,
+        #      - we check if the version number exists in the file already (for republishing docs)
+        #      - if it's an alias (stage/latest/*) or old version, we do nothing and output $o (original input)
+        #      - if it's a new version number, we add it at position 0 in the array.
+        #   4. Once done, we'll upload it back to S3.
+        run: |
+          aws s3 cp \
+            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json \
+            versions_old.json
+          jq 'del(.[].aliases[] | select(. == "${{ env.ALIAS }}"))' < versions_old.json > versions_proc.json
+          jq '. as $o | [{"title": "${{ env.VERSION }}", "version": "${{ env.VERSION }}", "aliases": ["${{ env.ALIAS }}"] }] as $n | $n | if .[0].title | test("[a-z]+") or any($o[].title == $n[0].title;.) then [($o | .[] | select(.title == $n[0].title).aliases += $n[0].aliases | . )] else $n + $o end' < versions_proc.json > versions.json
+          aws s3 cp \
+            versions.json \
+            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json

.github/workflows/release.yml

@@ -20,7 +20,7 @@
 #
 # Triggers:
 #   - workflow_dispatch
-# 
+#
 #  Secrets:
 #   - RELEASE.GPG_SIGNING_KEY
 #   - RELEASE.OSSRH_JIRA_USERNAME
@@ -39,23 +39,23 @@ on:
         type: boolean
         description: Create snapshot release
         default: false
-      skip_checks: 
+      skip_checks:
         type: boolean
         description: Skip quality checks
         default: false
       skip_publish:
         type: boolean
         description: Skip publish to Maven Central
         default: false
-      continue_on_error: 
+      continue_on_error:
         type: boolean
         description: Continue to build if there's an error in quality checks
         default: false
 
 name: Release
 run-name: Release – ${{ inputs.version }}
 
-permissions: 
+permissions:
   contents: read
 
 env:
@@ -124,7 +124,7 @@ jobs:
 
   quality:
     runs-on: ubuntu-latest
-    needs: 
+    needs:
       - version_seal
     if: ${{ inputs.skip_checks == false }}
     permissions:
@@ -211,7 +211,7 @@ jobs:
           MAVEN_USERNAME: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
           MAVEN_PASSWORD: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}
           GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
-  
+
   create_pr:
     runs-on: ubuntu-latest
     if: ${{ inputs.snapshot == false && always() && !contains(needs.*.result, 'failure') && !contains(needs.*.result, 'cancelled') }}
@@ -270,24 +270,57 @@ jobs:
       id-token: write
     environment: Docs
     steps:
-      - id: download_source
-        name: Download artifacts
-        uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.6.1
-        with:
-          name: source
+      - id: checkout
+        name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - name: Build
         run: |
           mkdir -p dist
           docker build -t squidfunk/mkdocs-material ./docs/
           docker run --rm -t -v ${PWD}:/docs squidfunk/mkdocs-material build
-          cp -R site/* dist/
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@ececac1a45f3b08a01d2dd070d28d111c5fe6722
         with:
           aws-region: us-east-1
           role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }}
-      - name: Deploy
+      - name: Deploy Docs (Version)
+        env:
+          VERSION: ${{ inputs.version }}
+          ALIAS: 'latest'
+        run: |
+          aws s3 sync \
+            site/ \
+            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.VERSION }}/
+      - name: Deploy Docs (Alias)
+        env:
+          VERSION: ${{ inputs.version }}
+          ALIAS: 'latest'
         run: |
           aws s3 sync \
-            dist \
-            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/
+            site/ \
+            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.ALIAS }}/
+      - name: Deploy Docs (Version JSON)
+        env:
+          VERSION: ${{ inputs.version }}
+          ALIAS: 'latest'
+        # We originally used "mike" from PyPi to manage versions for us, but since we moved to S3, we can't use it to manage versions any more.
+        # Instead, we're using some shell script that manages the versions.
+        #
+        # Operations:
+        #   1. Download the versions.json file from S3
+        #   2. Find any reference to the alias and delete it from the versions file
+        #   3. This is voodoo (don't use JQ):
+        #      - we assign the input as $o and the new version/alias as $n,
+        #      - we check if the version number exists in the file already (for republishing docs)
+        #      - if it's an alias (stage/latest/*) or old version, we do nothing and output $o (original input)
+        #      - if it's a new version number, we add it at position 0 in the array.
+        #   4. Once done, we'll upload it back to S3.
+        run: |
+          aws s3 cp \
+            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json \
+            versions_old.json
+          jq 'del(.[].aliases[] | select(. == "${{ env.ALIAS }}"))' < versions_old.json > versions_proc.json
+          jq '. as $o | [{"title": "${{ env.VERSION }}", "version": "${{ env.VERSION }}", "aliases": ["${{ env.ALIAS }}"] }] as $n | $n | if .[0].title | test("[a-z]+") or any($o[].title == $n[0].title;.) then [($o | .[] | select(.title == $n[0].title).aliases += $n[0].aliases | . )] else $n + $o end' < versions_proc.json > versions.json
+          aws s3 cp \
+            versions.json \
+            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json

README.md

@@ -22,17 +22,17 @@ Powertools for AWS Lambda (Java) is available in Maven Central. You can use your
     <dependency>
         <groupId>software.amazon.lambda</groupId>
         <artifactId>powertools-tracing</artifactId>
-        <version>2.0.0-SNAPSHOT</version>
+        <version>2.0.0</version>
     </dependency>
     <dependency>
         <groupId>software.amazon.lambda</groupId>
         <artifactId>powertools-logging</artifactId>
-        <version>2.0.0-SNAPSHOT</version>
+        <version>2.0.0</version>
     </dependency>
     <dependency>
         <groupId>software.amazon.lambda</groupId>
         <artifactId>powertools-metrics</artifactId>
-        <version>2.0.0-SNAPSHOT</version>
+        <version>2.0.0</version>
     </dependency>
     ...
 </dependencies>

docs/FAQs.md

@@ -3,16 +3,15 @@ title: FAQs
 description: Frequently Asked Questions
 ---
 
-
 ## How can I use Powertools for AWS Lambda (Java) with Lombok?
 
-Powertools uses `aspectj-maven-plugin` to compile-time weave (CTW) aspects into the project. In case you want to use `Lombok` or other compile-time preprocessor for your project, it is required to change `aspectj-maven-plugin` configuration to enable in-place weaving feature. Otherwise the plugin will ignore changes introduced by `Lombok` and will use `.java` files as a source. 
+Many utilities in this library use `aspectj-maven-plugin` to compile-time weave (CTW) aspects into the project. In case you want to use `Lombok` or other compile-time preprocessor for your project, it is required to change `aspectj-maven-plugin` configuration to enable in-place weaving feature. Otherwise the plugin will ignore changes introduced by `Lombok` and will use `.java` files as a source.
 
 To enable in-place weaving feature you need to use following `aspectj-maven-plugin` configuration:
 
 ```xml hl_lines="2-6"
 <configuration>
-    <forceAjcCompile>true</forceAjcCompile> 
+    <forceAjcCompile>true</forceAjcCompile>
     <sources/>
     <weaveDirectories>
         <weaveDirectory>${project.build.directory}/classes</weaveDirectory>
@@ -29,14 +28,14 @@ To enable in-place weaving feature you need to use following `aspectj-maven-plug
 
 ## How can I use Powertools for AWS Lambda (Java) with Kotlin projects?
 
-Powertools uses `aspectj-maven-plugin` to compile-time weave (CTW) aspects into the project. When using it with Kotlin projects, it is required to `forceAjcCompile`. 
-No explicit configuration should be required for gradle projects. 
+Many utilities use `aspectj-maven-plugin` to compile-time weave (CTW) aspects into the project. When using it with Kotlin projects, it is required to `forceAjcCompile`.
+No explicit configuration should be required for gradle projects.
 
 To enable `forceAjcCompile` you need to use following `aspectj-maven-plugin` configuration:
 
 ```xml hl_lines="2"
 <configuration>
-    <forceAjcCompile>true</forceAjcCompile> 
+    <forceAjcCompile>true</forceAjcCompile>
     ...
     <aspectLibraries>
         <aspectLibrary>
@@ -49,17 +48,17 @@ To enable `forceAjcCompile` you need to use following `aspectj-maven-plugin` con
 
 ## How can I use Powertools for AWS Lambda (Java) with the AWS CRT HTTP Client?
 
-Powertools uses the `url-connection-client` as the default HTTP client. The `url-connection-client` is a lightweight HTTP client, which keeps the impact on Lambda cold starts to a minimum. 
-With the [announcement](https://aws.amazon.com/blogs/developer/announcing-availability-of-the-aws-crt-http-client-in-the-aws-sdk-for-java-2-x/) of the `aws-crt-client` a new HTTP client has been released, which offers faster SDK startup time and smaller memory footprint. 
+Utilities relying on AWS SDK clients use the `url-connection-client` as the default HTTP client. The `url-connection-client` is a lightweight HTTP client, which keeps the impact on Lambda cold starts to a minimum.
+With the [announcement](https://aws.amazon.com/blogs/developer/announcing-availability-of-the-aws-crt-http-client-in-the-aws-sdk-for-java-2-x/) of the `aws-crt-client` a new HTTP client has been released, which offers faster SDK startup time and smaller memory footprint.
 
-Unfortunately, replacing the `url-connection-client` dependency with the `aws-crt-client` will not immediately improve the lambda cold start performance and memory footprint, 
-as the default version of the dependency contains native system libraries for all supported runtimes and architectures (Linux, MacOS, Windows, AMD64, ARM64, etc).  This makes the CRT client portable, without the user having to consider _where_ their code will run, but comes at the cost of JAR size.
+Unfortunately, replacing the `url-connection-client` dependency with the `aws-crt-client` will not immediately improve the lambda cold start performance and memory footprint,
+as the default version of the dependency contains native system libraries for all supported runtimes and architectures (Linux, MacOS, Windows, AMD64, ARM64, etc). This makes the CRT client portable, without the user having to consider _where_ their code will run, but comes at the cost of JAR size.
 
 ### Configuring dependencies
 
-Using the `aws-crt-client` in your project requires the exclusion of the `url-connection-client` transitive dependency from the powertools dependency. 
+Using the `aws-crt-client` in your project requires the exclusion of the `url-connection-client` transitive dependency from the `powertools-*` dependency.
 
-```xml 
+```xml
 <dependency>
     <groupId>software.amazon.lambda</groupId>
     <artifactId>powertools-parameters</artifactId>
@@ -72,8 +71,9 @@ Using the `aws-crt-client` in your project requires the exclusion of the `url-co
     </exclusions>
 </dependency>
 ```
-Next, add the `aws-crt-client` and exclude the "generic" `aws-crt` dependency (contains all runtime libraries). 
-Instead, set a specific classifier of the `aws-crt` to use the one for your target runtime: either `linux-x86_64` for a Lambda configured for x86 or `linux-aarch_64` for Lambda using arm64. 
+
+Next, add the `aws-crt-client` and exclude the "generic" `aws-crt` dependency (contains all runtime libraries).
+Instead, set a specific classifier of the `aws-crt` to use the one for your target runtime: either `linux-x86_64` for a Lambda configured for x86 or `linux-aarch_64` for Lambda using arm64.
 
 !!! note "You will need to add a separate maven profile to build and debug locally when your development environment does not share the target architecture you are using in Lambda."
 By specifying the specific target runtime, we prevent other target runtimes from being included in the jar file, resulting in a smaller Lambda package and improved cold start times.
@@ -102,10 +102,11 @@ By specifying the specific target runtime, we prevent other target runtimes from
 ```
 
 ### Explicitly set the AWS CRT HTTP Client
-After configuring the dependencies, it's required to explicitly specify the AWS SDK HTTP client. 
-Depending on the Powertools module, there is a different way to configure the SDK client.
 
-The following example shows how to use the Lambda Powertools Parameters module while leveraging the AWS CRT Client.   
+After configuring the dependencies, it's required to explicitly specify the AWS SDK HTTP client.
+Depending on the utility you are using, there is a different way to configure the SDK client.
+
+The following example shows how to use the Parameters module while leveraging the AWS CRT Client.
 
 ```java hl_lines="16 23-24"
 import static software.amazon.lambda.powertools.parameters.transform.Transformer.base64;
@@ -141,12 +142,12 @@ public class RequestHandlerWithParams implements RequestHandler<String, String>
 }
 ```
 
-The `aws-crt-client` was considered for adoption as the default HTTP client in Lambda Powertools for Java as mentioned in [Move SDK http client to CRT](https://github.com/aws-powertools/powertools-lambda-java/issues/1092), 
+The `aws-crt-client` was considered for adoption as the default HTTP client in Powertools for AWS Lambda (Java) as mentioned in [Move SDK http client to CRT](https://github.com/aws-powertools/powertools-lambda-java/issues/1092),
 but due to the impact on the developer experience it was decided to stick with the `url-connection-client`.
 
 ## How can I use Powertools for AWS Lambda (Java) with GraalVM?
 
-Powertools core utilities, i.e. [logging](./core/logging.md), [metrics](./core/metrics.md) and [tracing](./core/tracing.md), include the [GraalVM Reachability Metadata (GRM)](https://www.graalvm.org/latest/reference-manual/native-image/metadata/) in the `META-INF` directories of the respective JARs. You can find a working example of Serverless Application Model (SAM) based application in the [examples](../examples/powertools-examples-core-utilities/sam-graalvm/README.md) directory.
+Core utilities, i.e. [logging](./core/logging.md), [metrics](./core/metrics.md) and [tracing](./core/tracing.md), include the [GraalVM Reachability Metadata (GRM)](https://www.graalvm.org/latest/reference-manual/native-image/metadata/) in the `META-INF` directories of the respective JARs. You can find a working example of Serverless Application Model (SAM) based application in the [examples](../examples/powertools-examples-core-utilities/sam-graalvm/README.md) directory.
 
 Below, you find typical steps you need to follow in a Maven based Java project:
 
@@ -157,6 +158,7 @@ export JAVA_HOME=<path to GraalVM>
 ```
 
 ### Use log4j `>2.24.0`
+
 Log4j version `2.24.0` adds [support for GraalVM](https://github.com/apache/logging-log4j2/issues/1539#issuecomment-2106766878). Depending on your project's dependency hierarchy, older version of log4j might be included in the final dependency graph. Make sure version `>2.24.0` of these dependencies are used by your Maven project:
 
 ```xml
@@ -245,10 +247,11 @@ Create a Docker image using a `Dockerfile` like [this](../examples/powertools-ex
 docker build --platform linux/amd64 . -t your-org/your-app-graalvm-builder
 ```
 
-Create the native image of you Lambda function using the Docker command below. 
+Create the native image of you Lambda function using the Docker command below.
 
 ```shell
 docker run --platform linux/amd64 -it -v `pwd`:`pwd` -w `pwd` -v ~/.m2:/root/.m2 your-org/your-app-graalvm-builder mvn clean -Pnative-image package
 
 ```
+
 The native image is created in the `target/` directory.