Merge branch 'main' into gh-actions-hash

Author: scottgerring

CONTRIBUTING.md

@@ -31,10 +31,11 @@ To send us a pull request, please:
 
 1. Fork the repository.
 2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
-3. Ensure local tests pass.
-4. Commit to your fork using clear commit messages.
-5. Send us a pull request, answering any default questions in the pull request interface.
-6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
+3. Ensure local tests pass: `mvn clean test`
+4. Ensure your code is formatted with the provided [checkstyle.xml](https://github.com/aws-powertools/powertools-lambda-java/blob/main/checkstyle.xml): `mvn clean verify`
+5. Commit to your fork using clear commit messages.
+6. Send us a pull request, answering any default questions in the pull request interface.
+7. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
 
 GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
 [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).

README.md

@@ -197,6 +197,15 @@ The following companies, among others, use Powertools:
 * [MkDocs](https://www.mkdocs.org/)
 * [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
 
+## Connect
+
+* **Powertools for AWS Lambda on Discord**: `#java` - **[Invite link](https://discord.gg/B8zZKbbyET)**
+* **Email**: <[email protected]>
+
+## Security disclosures
+
+If you think you’ve found a potential security issue, please do not post it in the Issues.  Instead, please follow the instructions [here](https://aws.amazon.com/security/vulnerability-reporting/) or [email AWS security directly](mailto:[email protected]).
+
 ## License
 
 This library is licensed under the Apache License, Version 2.0. See the LICENSE file.

checkstyle.xml

@@ -239,7 +239,7 @@ to customise what is logged.
      */
     public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
 
-        Logger log = LogManager.getLogger();
+        Logger log = LogManager.getLogger(App.class);
 
         @Logging
         public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
@@ -256,7 +256,7 @@ to customise what is logged.
      */
     public class AppLogEvent implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
 
-        Logger log = LogManager.getLogger();
+        Logger log = LogManager.getLogger(AppLogEvent.class);
 
         @Logging(logEvent = true)
         public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
@@ -315,7 +315,7 @@ You can set a Correlation ID using `correlationIdPath` attribute by passing a [J
      */
     public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
 
-        Logger log = LogManager.getLogger();
+        Logger log = LogManager.getLogger(App.class);
 
         @Logging(correlationIdPath = "/headers/my_request_id_header")
         public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
@@ -364,7 +364,7 @@ for known event sources, where either a request ID or X-Ray Trace ID are present
      */
     public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
 
-        Logger log = LogManager.getLogger();
+        Logger log = LogManager.getLogger(App.class);
 
         @Logging(correlationIdPath = CorrelationIdPathConstants.API_GATEWAY_REST)
         public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
@@ -417,7 +417,7 @@ You can append your own keys to your existing logs via `appendKey`.
      */
     public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
 
-        Logger log = LogManager.getLogger();
+        Logger log = LogManager.getLogger(App.class);
 
         @Logging(logEvent = true)
         public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
@@ -449,7 +449,7 @@ You can remove any additional key from entry using `LoggingUtils.removeKeys()`.
      */
     public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
 
-        Logger log = LogManager.getLogger();
+        Logger log = LogManager.getLogger(App.class);
 
         @Logging(logEvent = true)
         public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
@@ -484,7 +484,7 @@ this means that custom keys can be persisted across invocations. If you want all
      */
     public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
 
-        Logger log = LogManager.getLogger();
+        Logger log = LogManager.getLogger(App.class);
 
         @Logging(clearState = true)
         public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
@@ -545,7 +545,7 @@ specific fields from received event due to security.
      */
     public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
 
-        Logger log = LogManager.getLogger();
+        Logger log = LogManager.getLogger(App.class);
 
         static {
             ObjectMapper objectMapper = new ObjectMapper();
@@ -575,7 +575,7 @@ via `samplingRate` attribute on annotation.
      */
     public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
 
-        Logger log = LogManager.getLogger();
+        Logger log = LogManager.getLogger(App.class);
 
         @Logging(samplingRate = 0.5)
         public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {

docs/core/logging.md

@@ -3,7 +3,7 @@
 This directory holds example projects demoing different components of the Powertools for AWS Lambda (Java).
 Each example can be copied from its subdirectory and used independently of the rest of this repository.
 
-## The Examples
+## Examples
 
 * [powertools-examples-core](powertools-examples-core) - Demonstrates the core logging, tracing, and metrics modules 
 * [powertools-examples-idempotency](powertools-examples-idempotency) - An idempotent HTTP API
@@ -51,6 +51,17 @@ The first command will build the source of your application. The second command
 
 You can find your API Gateway Endpoint URL in the output values displayed after deployment.
 
+### External examples
+
+You can find more examples in the https://github.com/aws/aws-sam-cli-app-templates project:
+
+* [Java 8 + Maven](https://github.com/aws/aws-sam-cli-app-templates/tree/master/java8/hello-pt-maven)
+* [Java 8 on Amazon Linux 2 + Maven](https://github.com/aws/aws-sam-cli-app-templates/tree/master/java8.al2/hello-pt-maven)
+* [Java 11 + Maven](https://github.com/aws/aws-sam-cli-app-templates/tree/master/java11/hello-pt-maven)
+* [Java 17 + Maven](https://github.com/aws/aws-sam-cli-app-templates/tree/master/java17/hello-pt-maven)
+* [Java 17 + Gradle](https://github.com/aws/aws-sam-cli-app-templates/tree/master/java17/hello-pt-gradle)
+
+
 ### SAM - Other Tools 
 
 If you prefer to use an integrated development environment (IDE) to build and test your application, you can use the AWS Toolkit.  

examples/README.md

@@ -1,4 +1,18 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright 2023 Amazon.com, Inc. or its affiliates.
+  ~ Licensed under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License.  You may obtain a copy of the License at
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  ~
+  -->
+
 <project xmlns="http://maven.apache.org/POM/4.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

examples/pom.xml

@@ -7,8 +7,9 @@ public class PowertoolsExamplesCloudformationCdkApp {
     public static void main(final String[] args) {
         App app = new App();
 
-        new PowertoolsExamplesCloudformationCdkStack(app, "PowertoolsExamplesCloudformationCdkStack", StackProps.builder()
-                .build());
+        new PowertoolsExamplesCloudformationCdkStack(app, "PowertoolsExamplesCloudformationCdkStack",
+                StackProps.builder()
+                        .build());
 
         app.synth();
     }

examples/powertools-examples-cloudformation/infra/cdk/src/main/java/com/myorg/PowertoolsExamplesCloudformationCdkApp.java

@@ -16,7 +16,7 @@
         <maven.deploy.skip>true</maven.deploy.skip>
         <lambda.core.version>1.2.2</lambda.core.version>
         <lambda.events.version>3.11.2</lambda.events.version>
-        <aws.sdk.version>2.20.108</aws.sdk.version>
+        <aws.sdk.version>2.20.111</aws.sdk.version>
     </properties>
     <dependencyManagement>
         <dependencies>

examples/powertools-examples-cloudformation/pom.xml

@@ -41,7 +41,8 @@ public App() {
     protected Response create(CloudFormationCustomResourceEvent cloudFormationCustomResourceEvent, Context context) {
         // Validate the CloudFormation Custom Resource event
         Objects.requireNonNull(cloudFormationCustomResourceEvent, "cloudFormationCustomResourceEvent cannot be null.");
-        Objects.requireNonNull(cloudFormationCustomResourceEvent.getResourceProperties().get("BucketName"), "BucketName cannot be null.");
+        Objects.requireNonNull(cloudFormationCustomResourceEvent.getResourceProperties().get("BucketName"),
+                "BucketName cannot be null.");
 
         log.info(cloudFormationCustomResourceEvent);
         String bucketName = (String) cloudFormationCustomResourceEvent.getResourceProperties().get("BucketName");
@@ -70,7 +71,8 @@ protected Response create(CloudFormationCustomResourceEvent cloudFormationCustom
     protected Response update(CloudFormationCustomResourceEvent cloudFormationCustomResourceEvent, Context context) {
         // Validate the CloudFormation Custom Resource event
         Objects.requireNonNull(cloudFormationCustomResourceEvent, "cloudFormationCustomResourceEvent cannot be null.");
-        Objects.requireNonNull(cloudFormationCustomResourceEvent.getResourceProperties().get("BucketName"), "BucketName cannot be null.");
+        Objects.requireNonNull(cloudFormationCustomResourceEvent.getResourceProperties().get("BucketName"),
+                "BucketName cannot be null.");
 
         log.info(cloudFormationCustomResourceEvent);
         // Get the physicalResourceId. physicalResourceId is the value returned to CloudFormation in the Create request, and passed in on subsequent requests (e.g. UPDATE or DELETE)
@@ -112,7 +114,8 @@ protected Response update(CloudFormationCustomResourceEvent cloudFormationCustom
     protected Response delete(CloudFormationCustomResourceEvent cloudFormationCustomResourceEvent, Context context) {
         // Validate the CloudFormation Custom Resource event
         Objects.requireNonNull(cloudFormationCustomResourceEvent, "cloudFormationCustomResourceEvent cannot be null.");
-        Objects.requireNonNull(cloudFormationCustomResourceEvent.getPhysicalResourceId(), "PhysicalResourceId cannot be null.");
+        Objects.requireNonNull(cloudFormationCustomResourceEvent.getPhysicalResourceId(),
+                "PhysicalResourceId cannot be null.");
 
         log.info(cloudFormationCustomResourceEvent);
         // Get the physicalResourceId. physicalResourceId is the value provided to CloudFormation in the Create request.
@@ -142,7 +145,8 @@ protected Response delete(CloudFormationCustomResourceEvent cloudFormationCustom
 
     private boolean bucketExists(String bucketName) {
         try {
-            HeadBucketResponse headBucketResponse = s3Client.headBucket(HeadBucketRequest.builder().bucket(bucketName).build());
+            HeadBucketResponse headBucketResponse =
+                    s3Client.headBucket(HeadBucketRequest.builder().bucket(bucketName).build());
             if (headBucketResponse.sdkHttpResponse().isSuccessful()) {
                 return true;
             }
@@ -157,7 +161,8 @@ private void createBucket(String bucketName) {
         S3Waiter waiter = s3Client.waiter();
         CreateBucketRequest createBucketRequest = CreateBucketRequest.builder().bucket(bucketName).build();
         s3Client.createBucket(createBucketRequest);
-        WaiterResponse<HeadBucketResponse> waiterResponse = waiter.waitUntilBucketExists(HeadBucketRequest.builder().bucket(bucketName).build());
+        WaiterResponse<HeadBucketResponse> waiterResponse =
+                waiter.waitUntilBucketExists(HeadBucketRequest.builder().bucket(bucketName).build());
         waiterResponse.matched().response().ifPresent(log::info);
         log.info("Bucket Created {}", bucketName);
     }

examples/powertools-examples-cloudformation/src/main/java/helloworld/App.java

@@ -1,34 +1,47 @@
+/*
+ * Copyright 2023 Amazon.com, Inc. or its affiliates.
+ * Licensed under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
 package helloworld;
 
-import java.io.BufferedReader;
-import java.io.IOException;
-import java.io.InputStreamReader;
-import java.net.URL;
-import java.util.HashMap;
-import java.util.Map;
-import java.util.stream.Collectors;
+import static software.amazon.lambda.powertools.metrics.MetricsUtils.metricsLogger;
+import static software.amazon.lambda.powertools.metrics.MetricsUtils.withSingleMetric;
+import static software.amazon.lambda.powertools.tracing.TracingUtils.putMetadata;
+import static software.amazon.lambda.powertools.tracing.TracingUtils.withEntitySubsegment;
 
 import com.amazonaws.services.lambda.runtime.Context;
 import com.amazonaws.services.lambda.runtime.RequestHandler;
 import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
 import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
 import com.amazonaws.xray.AWSXRay;
 import com.amazonaws.xray.entities.Entity;
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.net.URL;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.stream.Collectors;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 import software.amazon.cloudwatchlogs.emf.model.DimensionSet;
 import software.amazon.cloudwatchlogs.emf.model.Unit;
-import software.amazon.lambda.powertools.logging.LoggingUtils;
 import software.amazon.lambda.powertools.logging.Logging;
+import software.amazon.lambda.powertools.logging.LoggingUtils;
 import software.amazon.lambda.powertools.metrics.Metrics;
 import software.amazon.lambda.powertools.tracing.CaptureMode;
-import software.amazon.lambda.powertools.tracing.TracingUtils;
 import software.amazon.lambda.powertools.tracing.Tracing;
-
-import static software.amazon.lambda.powertools.metrics.MetricsUtils.metricsLogger;
-import static software.amazon.lambda.powertools.metrics.MetricsUtils.withSingleMetric;
-import static software.amazon.lambda.powertools.tracing.TracingUtils.putMetadata;
-import static software.amazon.lambda.powertools.tracing.TracingUtils.withEntitySubsegment;
+import software.amazon.lambda.powertools.tracing.TracingUtils;
 
 /**
  * Handler for requests to Lambda function.
@@ -47,10 +60,11 @@ public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEv
 
         metricsLogger().putMetric("CustomMetric1", 1, Unit.COUNT);
 
-        withSingleMetric("CustomMetrics2", 1, Unit.COUNT, "Another", (metric) -> {
-            metric.setDimensions(DimensionSet.of("AnotherService", "CustomService"));
-            metric.setDimensions(DimensionSet.of("AnotherService1", "CustomService1"));
-        });
+        withSingleMetric("CustomMetrics2", 1, Unit.COUNT, "Another", (metric) ->
+            {
+                metric.setDimensions(DimensionSet.of("AnotherService", "CustomService"));
+                metric.setDimensions(DimensionSet.of("AnotherService1", "CustomService1"));
+            });
 
         LoggingUtils.appendKey("test", "willBeLogged");
 
@@ -62,11 +76,12 @@ public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEv
             TracingUtils.putAnnotation("Test", "New");
             String output = String.format("{ \"message\": \"hello world\", \"location\": \"%s\" }", pageContents);
 
-            TracingUtils.withSubsegment("loggingResponse", subsegment -> {
-                String sampled = "log something out";
-                log.info(sampled);
-                log.info(output);
-            });
+            TracingUtils.withSubsegment("loggingResponse", subsegment ->
+                {
+                    String sampled = "log something out";
+                    log.info(sampled);
+                    log.info(output);
+                });
 
             threadOption1();
 
@@ -91,10 +106,11 @@ private void threadOption1() throws InterruptedException {
 
     private void threadOption2() throws InterruptedException {
         Entity traceEntity = AWSXRay.getTraceEntity();
-        Thread anotherThread = new Thread(() -> withEntitySubsegment("inlineLog", traceEntity, subsegment -> {
-            String var = "somethingToProcess";
-            log.info("inside threaded logging inline {}", var);
-        }));
+        Thread anotherThread = new Thread(() -> withEntitySubsegment("inlineLog", traceEntity, subsegment ->
+            {
+                String var = "somethingToProcess";
+                log.info("inside threaded logging inline {}", var);
+            }));
         anotherThread.start();
         anotherThread.join();
     }

examples/powertools-examples-core/src/main/java/helloworld/App.java

@@ -1,13 +1,26 @@
+/*
+ * Copyright 2023 Amazon.com, Inc. or its affiliates.
+ * Licensed under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
 package helloworld;
 
+import com.amazonaws.services.lambda.runtime.Context;
+import com.amazonaws.services.lambda.runtime.RequestStreamHandler;
+import com.fasterxml.jackson.databind.ObjectMapper;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
 import java.util.Map;
-
-import com.amazonaws.services.lambda.runtime.Context;
-import com.amazonaws.services.lambda.runtime.RequestStreamHandler;
-import com.fasterxml.jackson.databind.ObjectMapper;
 import software.amazon.lambda.powertools.logging.Logging;
 import software.amazon.lambda.powertools.metrics.Metrics;