From b5f4fccfa504fefb17dfa3028e4949339b02b9d7 Mon Sep 17 00:00:00 2001
From: msailes <msailes@amazon.co.uk>
Date: Tue, 18 Aug 2020 14:57:31 +0100
Subject: [PATCH 1/2] docs: Initial javadocs for our logging annotation.

---
 .../lambda/logging/PowerToolsLogging.java     | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/src/main/java/software/amazon/lambda/logging/PowerToolsLogging.java b/src/main/java/software/amazon/lambda/logging/PowerToolsLogging.java
index 98ade6924..d21e4d583 100644
--- a/src/main/java/software/amazon/lambda/logging/PowerToolsLogging.java
+++ b/src/main/java/software/amazon/lambda/logging/PowerToolsLogging.java
@@ -5,6 +5,43 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * {@code PowerToolsLogging} is used to signal that the annotated method should be
+ * extended with PowerToolsLogging functionality.
+ *
+ * <p>{@code PowerToolsLogging} provides an opinionated logger with output structured as JSON.</p>
+ *
+ * <p>{@code PowerToolsLogging} should be used with handleRequest method of a class
+ * which implements either
+ * {@code com.amazonaws.services.lambda.runtime.RequestHandler} or
+ * {@code com.amazonaws.services.lambda.runtime.RequestStreamHandler}.</p>
+ *
+ * <p>By default {@code PowerToolsLogging} will load the following keys and values from the Lambda
+ * {@code com.amazonaws.services.lambda.runtime.Context}</p>
+ *
+ * <ul>
+ *     <li>FunctionName</li>
+ *     <li>FunctionVersion</li>
+ *     <li>InvokedFunctionArn</li>
+ *     <li>MemoryLimitInMB</li>
+ * </ul>
+ *
+ * <p>By default {@code PowerToolsLogging} will also create keys for:</p>
+ *
+ * <ul>
+ *     <li>coldStart - True if this is the first invocation of this Lambda execution environment; else False</li>
+ *     <li>service - The value of the 'POWER_TOOLS_SERVICE_NAME' environment variable or 'service_undefined'</li>
+ * </ul>
+ *
+ * <p>These keys and values will be joined with the existing Log4J log event and written as JSON.</p>
+ *
+ * <p>The data and time of the log event will be written using {@link java.time.format.DateTimeFormatter#ISO_ZONED_DATE_TIME}</p>
+ *
+ * <p>By default {@code PowerToolsLogging} will not log the event which has trigger the invoke of the Lambda function.
+ * This can be enabled using {@code @PowerToolsLogging(logEvent = true)}.</p>
+ *
+ * <p>To append additional keys to each log entry you can use {@link software.amazon.lambda.logging.PowerLogger#customKey(String, String)}</p>
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface PowerToolsLogging {

From e427fed85e2039cfdcfae7a73aa14fa6e5d9dfab Mon Sep 17 00:00:00 2001
From: msailes <msailes@amazon.co.uk>
Date: Wed, 19 Aug 2020 13:05:12 +0100
Subject: [PATCH 2/2] docs: Initial javadocs for PowerLogger class.

---
 docs/content/core/logger.mdx                       |  4 ++--
 .../src/main/java/helloworld/App.java              |  2 +-
 .../amazon/lambda/logging/PowerLogger.java         | 14 +++++++++++++-
 .../amazon/lambda/logging/PowerToolsLogging.java   |  2 +-
 .../log4j/core/layout/LambdaJsonLayoutTest.java    |  2 +-
 .../amazon/lambda/logging/PowerLoggerTest.java     |  2 +-
 6 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/docs/content/core/logger.mdx b/docs/content/core/logger.mdx
index c9e33c68b..7cd21c5d4 100644
--- a/docs/content/core/logger.mdx
+++ b/docs/content/core/logger.mdx
@@ -114,7 +114,7 @@ public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatew
 
 ## Appending additional keys
 
-You can append your own keys to your existing Logger via `customKey`.
+You can append your own keys to your existing Logger via `appendKey`.
 
 ```java:title=App.java
 package helloworld;
@@ -135,7 +135,7 @@ public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatew
     @PowerToolsLogging(logEvent = true)
     public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
         ...
-        PowerLogger.customKey("test", "willBeLogged");
+        PowerLogger.appendKey("test", "willBeLogged");
         ...
     }
 }
diff --git a/example/HelloWorldFunction/src/main/java/helloworld/App.java b/example/HelloWorldFunction/src/main/java/helloworld/App.java
index c41e4ceb6..5369ffa1c 100644
--- a/example/HelloWorldFunction/src/main/java/helloworld/App.java
+++ b/example/HelloWorldFunction/src/main/java/helloworld/App.java
@@ -39,7 +39,7 @@ public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEv
         headers.put("Content-Type", "application/json");
         headers.put("X-Custom-Header", "application/json");
 
-        PowerLogger.customKey("test", "willBeLogged");
+        PowerLogger.appendKey("test", "willBeLogged");
 
         APIGatewayProxyResponseEvent response = new APIGatewayProxyResponseEvent()
                 .withHeaders(headers);
diff --git a/src/main/java/software/amazon/lambda/logging/PowerLogger.java b/src/main/java/software/amazon/lambda/logging/PowerLogger.java
index 5bb7365b2..8be69a49a 100644
--- a/src/main/java/software/amazon/lambda/logging/PowerLogger.java
+++ b/src/main/java/software/amazon/lambda/logging/PowerLogger.java
@@ -2,9 +2,21 @@
 
 import org.apache.logging.log4j.ThreadContext;
 
+/**
+ * A class of helper functions to add additional functionality to PowerToolsLogging.
+ *
+ * {@see PowerToolsLogging}
+ */
 public class PowerLogger {
 
-    public static void customKey(String key, String value) {
+    /**
+     * Appends an additional key and value to each log entry made. Duplicate values
+     * for the same key will be replaced with the latest.
+     *
+     * @param key The name of the key to be logged
+     * @param value The value to be logged
+     */
+    public static void appendKey(String key, String value) {
         ThreadContext.put(key, value);
     }
 }
diff --git a/src/main/java/software/amazon/lambda/logging/PowerToolsLogging.java b/src/main/java/software/amazon/lambda/logging/PowerToolsLogging.java
index d21e4d583..29333975e 100644
--- a/src/main/java/software/amazon/lambda/logging/PowerToolsLogging.java
+++ b/src/main/java/software/amazon/lambda/logging/PowerToolsLogging.java
@@ -40,7 +40,7 @@
  * <p>By default {@code PowerToolsLogging} will not log the event which has trigger the invoke of the Lambda function.
  * This can be enabled using {@code @PowerToolsLogging(logEvent = true)}.</p>
  *
- * <p>To append additional keys to each log entry you can use {@link software.amazon.lambda.logging.PowerLogger#customKey(String, String)}</p>
+ * <p>To append additional keys to each log entry you can use {@link software.amazon.lambda.logging.PowerLogger#appendKey(String, String)}</p>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
diff --git a/src/test/java/org/apache/logging/log4j/core/layout/LambdaJsonLayoutTest.java b/src/test/java/org/apache/logging/log4j/core/layout/LambdaJsonLayoutTest.java
index c99239648..40d6157d1 100644
--- a/src/test/java/org/apache/logging/log4j/core/layout/LambdaJsonLayoutTest.java
+++ b/src/test/java/org/apache/logging/log4j/core/layout/LambdaJsonLayoutTest.java
@@ -25,7 +25,7 @@
 
 class LambdaJsonLayoutTest {
 
-    private RequestHandler<Object, Object> handler = new PowerLogToolEnabled();
+    private final RequestHandler<Object, Object> handler = new PowerLogToolEnabled();
 
     @Mock
     private Context context;
diff --git a/src/test/java/software/amazon/lambda/logging/PowerLoggerTest.java b/src/test/java/software/amazon/lambda/logging/PowerLoggerTest.java
index fcec6f6ac..75e708c36 100644
--- a/src/test/java/software/amazon/lambda/logging/PowerLoggerTest.java
+++ b/src/test/java/software/amazon/lambda/logging/PowerLoggerTest.java
@@ -16,7 +16,7 @@ void setUp() {
 
     @Test
     void shouldSetCustomKeyOnThreadContext() {
-        PowerLogger.customKey("test", "value");
+        PowerLogger.appendKey("test", "value");
 
         assertThat(ThreadContext.getImmutableContext())
                 .hasSize(1)