Merge 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,19 @@ 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
+
+      # If matrix.version is 21, use 17, otherwise use matrix.version
+      # This is because AspectJ does not yet support weaving with Java21; we want
+      # to test the Java21 runtime, but we can't yet use the JDK21 compiler.
+      # https://github.com/eclipse-aspectj/aspectj/issues/260#issuecomment-1815920274
+      JAVA_VERSION: ${{ (matrix.java == 21 && '17') || matrix.java }}
+      JAVA_LAMBDA_RUNTIME_VERSION: ${{ matrix.java }}
     permissions:
       id-token: write # needed to interact with GitHub's OIDC Token endpoint.
       contents: read
@@ -49,7 +55,8 @@ jobs:
         uses: actions/setup-java@5ffc13f4174014e2d4d4572b3d74c3fa61aeb2c2 # v3.11.0
         with:
           distribution: 'corretto'
-          java-version: ${{ matrix.java }}
+          # See comment above on JAVA_VERSION env var
+          java-version: ${{ (matrix.java == 21 && '17') || matrix.java }}
           cache: maven
       - name: Setup AWS credentials
         uses: aws-actions/configure-aws-credentials@5fd3084fc36e372ff1fff382a39b10d03659f355 # v2.2.0

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,6 +11,14 @@ 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/)**
 
+### 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). 
+
+AspectJ does not yet support Java 21 [[1]](https://github.com/eclipse-aspectj/aspectj/issues/260), [[2]](https://github.com/eclipse-aspectj/aspectj/blob/master/docs/dist/doc/JavaVersionCompatibility.md).
+If you need to use aspects - either  Powertools features leveraging aspects or other libraries - you should use the JDK 17 compiler and target either the Java 17 or Java 21
+Lambda runtimes. 
+
 ### Installation
 
 Powertools for AWS Lambda (Java) is available in Maven Central. You can use your favourite dependency management tool to install it
@@ -22,17 +30,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>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>
@@ -192,7 +200,7 @@ Next, configure the aspectj-maven-plugin to compile-time weave (CTW) the aws-lam
 
 ## 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,48 @@ via `samplingRate` attribute on annotation.
                     POWERTOOLS_LOGGER_SAMPLE_RATE: 0.5
     ```
 
+## AWS Lambda Advanced Logging Controls
+With AWS [Lambda Advanced Logging Controls (ALC)](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-advanced), you can control the output format of your logs as either `TEXT` or `JSON` and specify the minimum accepted log level for your application. 
+Regardless of the output format setting in Lambda, Powertools for AWS Lambda will always output JSON formatted logging messages.
+
+When you have this feature enabled, log messages that don’t meet the configured log level are discarded by Lambda. 
+For example, if you set the minimum log level to `WARN`, you will only receive `WARN` and `ERROR` messages in your AWS CloudWatch Logs, all other log levels will be discarded by Lambda.
+
+```mermaid
+sequenceDiagram
+    participant Lambda service
+    participant Lambda function
+    participant Application Logger
+
+    Note over Lambda service: AWS_LAMBDA_LOG_LEVEL="WARN"
+    Lambda service->>Lambda function: Invoke (event)
+    Lambda function->>Lambda function: Calls handler
+    Lambda function->>Application Logger: logger.warn("Something happened")
+    Lambda function-->>Application Logger: logger.debug("Something happened")
+    Lambda function-->>Application Logger: logger.info("Something happened")
+    
+    Lambda service->>Lambda service: DROP INFO and DEBUG logs
+
+    Lambda service->>CloudWatch Logs: Ingest error logs
+```
+
+Logger will automatically listen for the `AWS_LAMBDA_LOG_FORMAT` and `AWS_LAMBDA_LOG_LEVEL` environment variables, and change behaviour if they’re found to ensure as much compatibility as possible.
+
+### Priority of log level settings in Powertools for AWS Lambda
+
+When the Advanced Logging Controls feature is 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) for more details.
+
+We prioritise log level settings in this order:
+
+1. `AWS_LAMBDA_LOG_LEVEL` environment variable
+2. `POWERTOOLS_LOG_LEVEL` environment variable
+
+In the event you have set `POWERTOOLS_LOG_LEVEL` to a level lower than the ACL setting, Powertools for AWS Lambda will output a warning log message informing you that your messages will be discarded by Lambda.
+
+### 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,10 +11,18 @@ 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.
 
+???+ tip "Java Compatability"
+    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).
+
+    AspectJ does not yet support Java 21 [[1]](https://github.com/eclipse-aspectj/aspectj/issues/260), [[2]](https://github.com/eclipse-aspectj/aspectj/blob/master/docs/dist/doc/JavaVersionCompatibility.md).
+    If you need to use aspects - either  Powertools features leveraging aspects or other libraries - you should use the JDK 17 compiler and target either the Java 17 or Java 21
+    Lambda runtimes. 
+
 ## Tenets
 
 This project separates core utilities that will be available in other runtimes vs general utilities that might not be available across all runtimes.
@@ -285,5 +293,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:1.19.0-SNAPSHOT'
+    aspect 'software.amazon.lambda:powertools-logging:1.19.0-SNAPSHOT'
+    aspect 'software.amazon.lambda:powertools-metrics:1.19.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

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";

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

@@ -16,6 +16,7 @@
 
 import static java.util.Optional.empty;
 import static java.util.Optional.of;
+import static software.amazon.lambda.powertools.common.internal.SystemWrapper.getProperty;
 import static software.amazon.lambda.powertools.common.internal.SystemWrapper.getenv;
 
 import com.amazonaws.services.lambda.runtime.Context;
@@ -46,6 +47,13 @@ public static boolean isHandlerMethod(final ProceedingJoinPoint pjp) {
         return placedOnRequestHandler(pjp) || placedOnStreamHandler(pjp);
     }
 
+    /**
+     * The class needs to implement RequestHandler interface
+     * The function needs to have exactly two arguments
+     * The second argument needs to be of type com.amazonaws.services.lambda.runtime.Context
+     * @param pjp
+     * @return
+     */
     public static boolean placedOnRequestHandler(final ProceedingJoinPoint pjp) {
         return RequestHandler.class.isAssignableFrom(pjp.getSignature().getDeclaringType())
                 && pjp.getArgs().length == 2
@@ -93,7 +101,12 @@ public static boolean isSamLocal() {
     }
 
     public static Optional<String> getXrayTraceId() {
-        final String X_AMZN_TRACE_ID = getenv(LambdaConstants.X_AMZN_TRACE_ID);
+        String X_AMZN_TRACE_ID = getenv(LambdaConstants.X_AMZN_TRACE_ID);
+        // For the Java Lambda 17+ runtime, the Trace ID is set as a System Property
+        if (X_AMZN_TRACE_ID == null) {
+            X_AMZN_TRACE_ID = getProperty(LambdaConstants.XRAY_TRACE_HEADER);
+        }
+
         if (X_AMZN_TRACE_ID != null) {
             return of(X_AMZN_TRACE_ID.split(";")[0].replace(LambdaConstants.ROOT_EQUALS, ""));
         }

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

@@ -21,4 +21,8 @@ private SystemWrapper() {
     public static String getenv(String name) {
         return System.getenv(name);
     }
+
+    public static String getProperty(String name) {
+        return System.getProperty(name);
+    }
 }

powertools-e2e-tests/pom.xml

@@ -31,7 +31,7 @@
         <maven.compiler.source>1.8</maven.compiler.source>
         <maven.compiler.target>1.8</maven.compiler.target>
         <constructs.version>10.3.0</constructs.version>
-        <cdk.version>2.100.0</cdk.version>
+        <cdk.version>2.109.0</cdk.version>
     </properties>
 
     <dependencies>

powertools-e2e-tests/src/test/java/software/amazon/lambda/powertools/LargeMessageIdempotentE2ET.java

@@ -107,7 +107,7 @@ public static void tearDown() {
     @Test
     public void test_ttlNotExpired_doesNotInsertInDDB_ttlExpired_insertInDDB() throws InterruptedException,
             IOException {
-        int waitMs = 10000;
+        int waitMs = 15000;
 
         // GIVEN
         InputStream inputStream = this.getClass().getResourceAsStream("/large_sqs_message.txt");

powertools-e2e-tests/src/test/java/software/amazon/lambda/powertools/LoggingE2ET.java

@@ -46,6 +46,7 @@ public class LoggingE2ET {
     public static void setup() {
         infrastructure = Infrastructure.builder()
                 .testName(LoggingE2ET.class.getSimpleName())
+                .tracing(true)
                 .pathToFunction("logging")
                 .environmentVariables(
                         Stream.of(new String[][] {
@@ -83,6 +84,7 @@ public void test_logInfoWithAdditionalKeys() throws JsonProcessingException {
         assertThat(jsonNode.get("message").asText()).isEqualTo("New Order");
         assertThat(jsonNode.get("orderId").asText()).isEqualTo(orderId);
         assertThat(jsonNode.get("coldStart").asBoolean()).isTrue();
+        assertThat(jsonNode.get("xray_trace_id").asText()).isNotBlank();
         assertThat(jsonNode.get("function_request_id").asText()).isEqualTo(invocationResult1.getRequestId());
 
         // second call should not be cold start