Merge pull request #1525 from aws-powertools/chore/main-into-v2

chore: Periodic merge of main into v2

Author: scottgerring

.github/workflows/pr_build.yml

@@ -49,7 +49,7 @@ jobs:
     strategy:
       max-parallel: 5
       matrix:
-        java: [8, 11, 17, 21, 15, 16, 18, 19, 20]
+        java: [8, 11, 17, 21]
     name: Java ${{ matrix.java }}
     env:
       JAVA: ${{ matrix.java }}

.github/workflows/run-e2e-tests.yml

@@ -33,13 +33,13 @@ jobs:
   e2e:
     runs-on: ubuntu-latest
     strategy:
-      max-parallel: 3
+      max-parallel: 4
       matrix:
-        java: [ 8, 11, 17 ]
+        java: [ 8, 11, 17, 21 ]
     name: End-to-end tests java${{ matrix.java }}
     env:
-      JAVA_VERSION: ${{ matrix.java }}
       AWS_DEFAULT_REGION: eu-west-1
+      JAVA_VERSION: ${{ matrix.java }}
     permissions:
       id-token: write # needed to interact with GitHub's OIDC Token endpoint.
       contents: read

CHANGELOG.md

@@ -8,6 +8,37 @@ This project follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) fo
 
 ## [Unreleased]
 
+## [1.18.0] - 2023-11-16
+
+### Added
+
+* feat: add support for [Lambda Advanced Logging Controls (ALC)](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-advanced) (#1514) by @jeromevdl
+* feat: Add support for POWERTOOLS_LOGGER_LOG_EVENT (#1510) by @AlexeySoshin
+
+### Maintenance
+
+* fix: json schema 403 error (#1457) by @jeromevdl
+* fix: array jmespath fail in idempotency module (#1420) by @jeromevdl
+* chore: java21 support in our build (#1488) by @jeromevdl
+* chore: Addition of Warn Message If Invalid Annotation Key While Tracing #1511 (#1512) by @jdoherty
+* fix: null namespace should fallback to default namespace (#1506) by @jeromevdl
+* fix: get trace id from system property when env var is not set (#1503) by @mriccia
+* chore: artifacts size on good branches (#1493) by @jeromevdl
+* fix: enforce jackson databind version (#1472) by @jeromevdl
+* chore: add missing projects and improve workflow (#1487) by @jeromevdl
+* chore: Reporting size of the jars in GitHub comments (#1196) by @jeromevdl
+* Deps: Bump third party dependencies to the latest versions.
+
+### Documentation
+
+* docs(customer-reference): add Vertex Pharmaceuticals as a customer reference (#1486) by @scottgerring
+* docs: Adding Kotlin example. (#1454) by @jasoniharris
+* docs: Terraform example (#1478) by @skal111
+* docs: Add Serveless Framework example (#1363) by @AlexeySoshin
+* docs: Fix link to SQS large message migration guide (#1422) by @scottgerring
+* docs(logging): correct log example keys (#1411) by @walmsles
+* docs: Update gradle configuration readme (#1359) by @scottgerring
+
 ## [1.17.0] - 2023-08-21
 
 ### Added

CONTRIBUTING.md

@@ -55,8 +55,7 @@ We strongly recommend installing the CheckStyle-IDEA plugin and apply the provid
 2. After installing the plugin, open the preferences (`⌘,` on macOS, or `Ctrl+Alt+S` on Windows/Linux) and search for _Code Style_. Click on the gear icon near the scheme and import checkstyle configuration. Click on "Apply" and "OK".
 ![](docs/media/intellij_checkstyle_1.png)
 
-3. Select the code you've created (module, package, class) and reformat code: `⌘⌥L` (macOS), or `Ctrl+Alt+L` (Windows/Linux):
-![](docs/media/intellij_checkstyle_2.png)
+3. Select the code you've created (module, package, class) and reformat code: `⌘⌥L` (macOS), or `Ctrl+Alt+L` (Windows/Linux).
 
 4. Apply the reformat, optimize imports, rearrange and cleanup to your code and only to java files:
 ![](docs/media/intellij_checkstyle_3.png)

README.md

@@ -11,28 +11,28 @@ Powertools for AWS Lambda (Java) is a developer toolkit to implement Serverless
 
 **[📜Documentation](https://docs.powertools.aws.dev/lambda-java/)** | **[Feature request](https://github.com/aws-powertools/powertools-lambda-java/issues/new?assignees=&labels=feature-request%2C+triage&template=feature_request.md&title=)** | **[🐛Bug Report](https://github.com/aws-powertools/powertools-lambda-java/issues/new?assignees=&labels=bug%2C+triage&template=bug_report.md&title=)** | **[Detailed blog post](https://aws.amazon.com/blogs/opensource/simplifying-serverless-best-practices-with-aws-lambda-powertools-java/)**
 
-### Installation
+## Installation
 
 Powertools for AWS Lambda (Java) is available in Maven Central. You can use your favourite dependency management tool to install it
 
-#### Maven:
+### Maven:
 ```xml
 <dependencies>
     ...
     <dependency>
         <groupId>software.amazon.lambda</groupId>
         <artifactId>powertools-tracing</artifactId>
-        <version>1.17.0</version>
+        <version>1.18.0</version>
     </dependency>
     <dependency>
         <groupId>software.amazon.lambda</groupId>
         <artifactId>powertools-logging</artifactId>
-        <version>1.17.0</version>
+        <version>1.18.0</version>
     </dependency>
     <dependency>
         <groupId>software.amazon.lambda</groupId>
         <artifactId>powertools-metrics</artifactId>
-        <version>1.17.0</version>
+        <version>1.18.0</version>
     </dependency>
     ...
 </dependencies>
@@ -190,9 +190,36 @@ Next, configure the aspectj-maven-plugin to compile-time weave (CTW) the aws-lam
 ```
 </details>
 
+### Java Compatibility
+Powertools for AWS Lambda (Java) supports all Java version from 8 up to 21 as well as the
+[corresponding Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html).
+For the modules that provide annotations, Powertools for AWS Lambda (Java) leverages the **aspectj** library.
+You may need to add the good version of `aspectjrt` to your dependencies based on the JDK used for building your function:
+
+```xml
+<dependency>
+    <groupId>org.aspectj</groupId>
+    <artifactId>aspectjrt</artifactId>
+    <version>1.9.??</version>
+</dependency>
+```
+
+<details>
+    <summary><b>JDK - aspectj dependency matrix</b></summary>
+
+| JDK version | aspectj version |
+|-------------|-----------------|
+| `1.8`       | `1.9.7`         |
+| `11-17`     | `1.9.20.1`      |
+| `21`        | `1.9.21`        |
+
+More info [here](https://github.com/aws-powertools/powertools-lambda-java/pull/1519/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R191).
+
+</details>
+
 ## Examples
 
-See the latest release of the **[examples](https://github.com/aws-powertools/powertools-lambda-java/tree/v1.17.0/examples)** for example projects showcasing usage of different utilities.
+See the latest release of the **[examples](https://github.com/aws-powertools/powertools-lambda-java/tree/v1.18.0/examples)** for example projects showcasing usage of different utilities.
 
 Have a demo project to contribute which showcase usage of different utilities from powertools? We are happy to accept it [here](CONTRIBUTING.md#security-issue-notifications).
 

docs/core/logging.md

@@ -217,9 +217,7 @@ Key | Type | Example | Description
 
 ## Capturing context Lambda info
 
-You can enrich your structured logs with key Lambda context information via `logEvent` annotation parameter. 
-You can also explicitly log any incoming event using `logEvent` param. Refer [Override default object mapper](#override-default-object-mapper) 
-to customise what is logged.
+When debugging in non-production environments, you can instruct Logger to log the incoming event with `@Logger(logEvent = true)` or via `POWERTOOLS_LOGGER_LOG_EVENT=true` environment variable.
 
 !!! warning
     Log event is disabled by default to prevent sensitive info being logged.
@@ -265,7 +263,7 @@ to customise what is logged.
     }
     ```
 
-### Customising  fields in logs
+### Customising fields in logs
 
 - Utility by default emits `timestamp` field in the logs in format `yyyy-MM-dd'T'HH:mm:ss.SSSZz` and in system default timezone. 
 If you need to customize format and timezone, you can do so by configuring `log4j2.component.properties` and configuring properties as shown in example below:
@@ -598,6 +596,54 @@ via `samplingRate` attribute on annotation.
                     POWERTOOLS_LOGGER_SAMPLE_RATE: 0.5
     ```
 
+## AWS Lambda Advanced Logging Controls (ALC)
+
+!!!question "When is it useful?"
+    When you want to set a logging policy to drop informational or verbose logs for one or all AWS Lambda functions, regardless of runtime and logger used.
+
+<!-- markdownlint-disable MD013 -->
+With [AWS Lambda Advanced Logging Controls (ALC)](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-advanced){target="_blank"}, you can enforce a minimum log level that Lambda will accept from your application code.
+
+When enabled, you should keep `Logger` and ALC log level in sync to avoid data loss.
+
+Here's a sequence diagram to demonstrate how ALC will drop both `INFO` and `DEBUG` logs emitted from `Logger`, when ALC log level is stricter than `Logger`.
+<!-- markdownlint-enable MD013 -->
+
+```mermaid
+sequenceDiagram
+    participant Lambda service
+    participant Lambda function
+    participant Application Logger
+
+    Note over Lambda service: AWS_LAMBDA_LOG_LEVEL="WARN"
+    Note over Application Logger: POWERTOOLS_LOG_LEVEL="DEBUG"
+
+    Lambda service->>Lambda function: Invoke (event)
+    Lambda function->>Lambda function: Calls handler
+    Lambda function->>Application Logger: logger.error("Something happened")
+    Lambda function-->>Application Logger: logger.debug("Something happened")
+    Lambda function-->>Application Logger: logger.info("Something happened")
+    Lambda service--xLambda service: DROP INFO and DEBUG logs
+    Lambda service->>CloudWatch Logs: Ingest error logs
+```
+
+### Priority of log level settings in Powertools for AWS Lambda
+
+We prioritise log level settings in this order:
+
+1. `AWS_LAMBDA_LOG_LEVEL` environment variable
+2. `POWERTOOLS_LOG_LEVEL` environment variable
+
+If you set `Logger` level lower than ALC, we will emit a warning informing you that your messages will be discarded by Lambda.
+
+> **NOTE**
+>
+> With ALC enabled, we are unable to increase the minimum log level below the `AWS_LAMBDA_LOG_LEVEL` environment variable value, see [AWS Lambda service documentation](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-log-level){target="_blank"} for more details.
+
+### Timestamp format
+
+When the Advanced Logging Controls feature is enabled, Powertools for AWS Lambda must comply with the timestamp format required by AWS Lambda, which is [RFC3339](https://www.rfc-editor.org/rfc/rfc3339). 
+In this case the format will be `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`.
 
 ## Upgrade to JsonTemplateLayout from deprecated LambdaJsonLayout configuration in log4j2.xml
 

docs/index.md

@@ -11,7 +11,7 @@ Powertools for AWS Lambda (Java) is a suite of utilities for AWS Lambda Function
     Powertools for AWS Lambda  is also available for [Python](https://docs.powertools.aws.dev/lambda/python/latest/){target="_blank"}, [TypeScript](https://docs.powertools.aws.dev/lambda/typescript/latest/){target="_blank"}, and [.NET](https://docs.powertools.aws.dev/lambda/dotnet/){target="_blank"}
 
 
-!!! tip "Looking for a quick run through of the core utilities?"
+???+ tip "Looking for a quick run through of the core utilities?"
     Check out [this detailed blog post](https://aws.amazon.com/blogs/opensource/simplifying-serverless-best-practices-with-aws-lambda-powertools-java/) with a practical example. To dive deeper, 
     the [Powertools for AWS Lambda (Java) workshop](https://catalog.us-east-1.prod.workshops.aws/workshops/a7011c82-e4af-4a52-80fa-fcd61f1dacd9/en-US/introduction) is a great next step.
 
@@ -274,6 +274,41 @@ Depending on your version of Java (either Java 1.8 or 11+), the configuration sl
     Under the hood, `org.codehaus.mojo:aspectj-maven-plugin` is based on AspectJ 1.9.7, 
     while `dev.aspectj:aspectj-maven-plugin` is based on AspectJ 1.9.8, compiled for Java 11+.
 
+### Java Compatibility
+Powertools for AWS Lambda (Java) supports all Java version from 8 up to 21 as well as the
+[corresponding Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html).
+
+For the following modules, Powertools for AWS Lambda (Java) leverages the **aspectj** library to provide annotations:
+- Logging
+- Metrics
+- Tracing
+- Parameters
+- Idempotency
+- Validation
+- Large messages
+
+
+You may need to add the good version of `aspectjrt` to your dependencies based on the jdk used for building your function:
+
+```xml
+<dependency>
+    <groupId>org.aspectj</groupId>
+    <artifactId>aspectjrt</artifactId>
+    <version>1.9.??</version>
+</dependency>
+```
+
+Use the following [dependency matrix](https://github.com/eclipse-aspectj/aspectj/blob/master/docs/dist/doc/JavaVersionCompatibility.md) between this library and the JDK:
+
+| JDK version | aspectj version |
+|-------------|-----------------|
+| `1.8`       | `1.9.7`         |
+| `11-17`     | `1.9.20.1`      |
+| `21`        | `1.9.21`        |
+
+_Note: 1.9.21 is not yet available and Java 21 not yet officially supported by aspectj, but you can already use the `1.9.21.M1`_
+
+
 ## Environment variables
 
 !!! info
@@ -285,5 +320,7 @@ Depending on your version of Java (either Java 1.8 or 11+), the configuration sl
 | **POWERTOOLS_METRICS_NAMESPACE** | Sets namespace used for metrics | [Metrics](./core/metrics) |
 | **POWERTOOLS_LOGGER_SAMPLE_RATE** | Debug log sampling | [Logging](./core/logging) |
 | **POWERTOOLS_LOG_LEVEL** | Sets logging level | [Logging](./core/logging) |
+| **POWERTOOLS_LOGGER_LOG_EVENT** | Enables/Disables whether to log the incoming event when using the aspect | [Logging](./core/logging) |
 | **POWERTOOLS_TRACER_CAPTURE_RESPONSE** | Enables/Disables tracing mode to capture method response | [Tracing](./core/tracing) |
 | **POWERTOOLS_TRACER_CAPTURE_ERROR** | Enables/Disables tracing mode to capture method error | [Tracing](./core/tracing) |
+

examples/powertools-examples-core-utilities/cdk/infra/pom.xml

@@ -7,7 +7,7 @@
     <version>2.0.0-SNAPSHOT</version>
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <cdk.version>2.93.0</cdk.version>
+        <cdk.version>2.100.0</cdk.version>
         <constructs.version>[10.0.0,11.0.0)</constructs.version>
         <junit.version>5.10.0</junit.version>
     </properties>

examples/powertools-examples-core-utilities/gradle/build.gradle

@@ -18,6 +18,7 @@ compileJava {
 }
 
 repositories {
+    mavenLocal()
     mavenCentral()
 }
 
@@ -27,8 +28,8 @@ dependencies {
     implementation 'com.fasterxml.jackson.core:jackson-databind:2.13.2.2'
     implementation 'com.amazonaws:aws-lambda-java-events:3.11.0'
     implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.13.2'
-    aspect 'software.amazon.lambda:powertools-tracing:1.17.0'
-    aspect 'software.amazon.lambda:powertools-logging:1.17.0'
-    aspect 'software.amazon.lambda:powertools-metrics:1.17.0'
+    aspect 'software.amazon.lambda:powertools-tracing:2.0.0-SNAPSHOT'
+    aspect 'software.amazon.lambda:powertools-logging:2.0.0-SNAPSHOT'
+    aspect 'software.amazon.lambda:powertools-metrics:2.0.0-SNAPSHOT'
 }
 

mkdocs.yml

@@ -85,7 +85,7 @@ extra_javascript:
 
 extra:
   powertools:
-    version: 1.17.0 # to update after each release (we do not want snapshot version here)
+    version: 1.18.0 # to update after each release (we do not want snapshot version here)
 
 repo_url: https://github.com/aws-powertools/powertools-lambda-java
 edit_uri: edit/main/docs

pom.xml

@@ -73,7 +73,6 @@
         <maven.compiler.target>1.8</maven.compiler.target>
         <log4j.version>2.20.0</log4j.version>
         <jackson.version>2.15.3</jackson.version>
-        <aspectj.version>1.9.7</aspectj.version>
         <aws.sdk.version>2.21.0</aws.sdk.version>
         <aws.xray.recorder.version>2.14.0</aws.xray.recorder.version>
         <payloadoffloading-common.version>2.1.3</payloadoffloading-common.version>
@@ -82,6 +81,7 @@
         <lambda.events.version>3.11.2</lambda.events.version>
         <lambda.serial.version>1.1.2</lambda.serial.version>
         <maven-compiler-plugin.version>3.11.0</maven-compiler-plugin.version>
+        <aspectj.version>1.9.7</aspectj.version>
         <aspectj-maven-plugin.version>1.13.1</aspectj-maven-plugin.version>
         <maven-surefire-plugin.version>3.1.2</maven-surefire-plugin.version>
         <jacoco-maven-plugin.version>0.8.10</jacoco-maven-plugin.version>
@@ -514,6 +514,7 @@
                 </plugins>
             </build>
         </profile>
+
         <profile>
             <id>jdk16</id>
             <activation>

powertools-cloudformation/pom.xml

@@ -76,6 +76,10 @@
             <groupId>com.fasterxml.jackson.core</groupId>
             <artifactId>jackson-databind</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.aspectj</groupId>
+            <artifactId>aspectjrt</artifactId>
+        </dependency>
 
         <!-- Test dependencies -->
         <dependency>
@@ -107,14 +111,6 @@
 
     <build>
         <plugins>
-            <plugin>
-                <groupId>dev.aspectj</groupId>
-                <artifactId>aspectj-maven-plugin</artifactId>
-                <version>${aspectj-maven-plugin.version}</version>
-                <configuration>
-                    <skip>true</skip>
-                </configuration>
-            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-checkstyle-plugin</artifactId>

powertools-common/src/main/java/software/amazon/lambda/powertools/common/internal/LambdaConstants.java

@@ -24,6 +24,7 @@ public class LambdaConstants {
     @Deprecated
     public static final String ON_DEMAND = "on-demand";
     public static final String X_AMZN_TRACE_ID = "_X_AMZN_TRACE_ID";
+    public static final String XRAY_TRACE_HEADER = "com.amazonaws.xray.traceHeader";
     public static final String AWS_SAM_LOCAL = "AWS_SAM_LOCAL";
     public static final String ROOT_EQUALS = "Root=";
     public static final String POWERTOOLS_SERVICE_NAME = "POWERTOOLS_SERVICE_NAME";