From 4f608fe67648f8e09cbeb9eea5138db61958f7b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Steve=20Houe=CC=88l?= Date: Mon, 17 Aug 2020 11:39:58 +0200 Subject: [PATCH 1/3] docs: Implement Logger and Tracer part --- docs/content/core/logger.mdx | 146 +++++++++++++++++++++++++++++++++++ docs/content/core/tracer.mdx | 16 ++++ docs/content/index.mdx | 40 ++++++++-- docs/gatsby-browser.js | 3 +- docs/gatsby-config.js | 12 +-- docs/package.json | 2 +- 6 files changed, 201 insertions(+), 18 deletions(-) create mode 100644 docs/content/core/logger.mdx create mode 100644 docs/content/core/tracer.mdx diff --git a/docs/content/core/logger.mdx b/docs/content/core/logger.mdx new file mode 100644 index 000000000..ecb28651d --- /dev/null +++ b/docs/content/core/logger.mdx @@ -0,0 +1,146 @@ +--- +title: Logger +description: Core utility +--- + +import Note from "../../src/components/Note" + +Logger provides an opinionated logger with output structured as JSON. + +**Key features** + +* Capture key fields from Lambda context, cold start and structures logging output as JSON +* Log Lambda event when instructed (disabled by default) + - Enable explicitly via annotation param +* Append additional keys to structured log at any point in time + +## Initialization + +Powertools extends the functionality of Log4J. Below is an example log4j2.xml file, with the LambdaJsonLayout configured. + +```xml + + + + + + + + + + + + + + + + +``` + +You can also explicitly set a service name via `POWERTOOLS_SERVICE_NAME` env var. This sets **service** key that will be present across all log statements. + +## Standard structured keys + +Your Logger will always include the following keys to your structured logging: + +Key | Type | Example | Description +------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------- +**timestamp** | String | "2020-05-24 18:17:33,774" | Timestamp of actual log statement +**level** | String | "INFO" | Logging level +**coldStart** | Boolean | true| ColdStart value. +**service** | String | "payment" | Service name defined. "service_undefined" will be used if unknown +**message** | String | "Collecting payment" | Log statement value. Unserializable JSON values will be casted to string + +## Capturing context Lambda info + +You can enrich your structured logs with key Lambda context information via `logEvent` annotation parameter. + +```java:title=App.java +package helloworld; + +import org.apache.logging.log4j.LogManager; +import org.apache.logging.log4j.Logger; +import software.amazon.lambda.logging.PowerLogger; +import software.amazon.lambda.logging.PowerToolsLogging; +... + +/** + * Handler for requests to Lambda function. + */ +public class App implements RequestHandler { + + Logger log = LogManager.getLogger(); + + @PowerToolsLogging() + public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) { + ... + } +} +``` + +You can also explicitly log any incoming event using `logEvent` param or via `POWERTOOLS_LOGGER_LOG_EVENT` env var. + + + This is disabled by default to prevent sensitive info being logged. +
+ +```java:title=App.java +package helloworld; + +import org.apache.logging.log4j.LogManager; +import org.apache.logging.log4j.Logger; +import software.amazon.lambda.logging.PowerLogger; +import software.amazon.lambda.logging.PowerToolsLogging; +... + +/** + * Handler for requests to Lambda function. + */ +public class App implements RequestHandler { + + Logger log = LogManager.getLogger(); + + @PowerToolsLogging(logEvent = true) + public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) { + ... + } +} +``` + +When used, this will include the following keys: + +Key | Type | Example +------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------- +**functionName**| String | "example-powertools-HelloWorldFunction-1P1Z6B39FLU73" +**functionVersion**| String | "12" +**functionMemorySize**| String | "128" +**functionArn**| String | "arn:aws:lambda:eu-west-1:012345678910:function:example-powertools-HelloWorldFunction-1P1Z6B39FLU73" + +## Appending additional keys + +You can append your own keys to your existing Logger via `customKey`. + +```java:title=App.java +package helloworld; + +import org.apache.logging.log4j.LogManager; +import org.apache.logging.log4j.Logger; +import software.amazon.lambda.logging.PowerLogger; +import software.amazon.lambda.logging.PowerToolsLogging; +... + +/** + * Handler for requests to Lambda function. + */ +public class App implements RequestHandler { + + Logger log = LogManager.getLogger(); + + @PowerToolsLogging(logEvent = true) + public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) { + ... + PowerLogger.customKey("test", "willBeLogged"); + ... + } +} +``` \ No newline at end of file diff --git a/docs/content/core/tracer.mdx b/docs/content/core/tracer.mdx new file mode 100644 index 000000000..a8fcbbd2c --- /dev/null +++ b/docs/content/core/tracer.mdx @@ -0,0 +1,16 @@ +--- +title: Tracer +description: Core utility +--- + +import Note from "../../src/components/Note" + +Tracer is an opinionated thin wrapper for [AWS X-Ray Java SDK](https://github.com/aws/aws-xray-sdk-java/). + +![Tracer showcase](../media/tracer_utility_showcase.png) + +**Key features** + +* Capture cold start as annotation, and responses as well as full exceptions as metadata +* Run functions locally with SAM CLI without code change to disable tracing +* Support tracing async methods \ No newline at end of file diff --git a/docs/content/index.mdx b/docs/content/index.mdx index 8ee26a12e..b544f7fbd 100644 --- a/docs/content/index.mdx +++ b/docs/content/index.mdx @@ -21,15 +21,39 @@ Powertools is available in Maven Central. You can use your favourite dependency ... ``` -* [gradle](https://gradle.org/): -``` -repositories { - mavenCentral() -} -dependencies { - powertools 'software.amazon.lambda:aws-lambda-powertools-java:YOUR_REQUIRED_VERSION' -} +And configure the aspectj-maven-plugin to compile-time weave (CTW) the aws-lambda-powertools-java aspects into your project: + +```xml + + + ... + + com.nickwongdev + aspectj-maven-plugin + 1.12.1 + + 1.8 + 1.8 + 1.8 + + + software.amazon.lambda + aws-lambda-powertools-java + + + + + + + compile + + + + + ... + + ``` ## Tenets diff --git a/docs/gatsby-browser.js b/docs/gatsby-browser.js index d029790c0..b5c868e23 100644 --- a/docs/gatsby-browser.js +++ b/docs/gatsby-browser.js @@ -8,7 +8,8 @@ export const onRouteUpdate = ({ location, prevLocation }) => { data: { url: window.location.href, section: location.pathname, - previous: prevLocation ? prevLocation.pathname : null + previous: prevLocation ? prevLocation.pathname : null, + language: 'java' }, streamName: awsconfig.aws_kinesis_firehose_stream_name }, 'AWSKinesisFirehose') diff --git a/docs/gatsby-config.js b/docs/gatsby-config.js index 9a3f102fb..07abebb99 100644 --- a/docs/gatsby-config.js +++ b/docs/gatsby-config.js @@ -17,15 +17,15 @@ module.exports = { menuTitle: 'Helpful resources', githubRepo: 'awslabs/aws-lambda-powertools-java', baseUrl: `${docsWebsite}`, - algoliaApiKey: 'a8491b576861e819fd50d567134eb9ce', - algoliaIndexName: 'aws-lambda-powertools-java', logoLink: `${docsWebsite}`, sidebarCategories: { null: [ 'index' ], - 'Core utilities': [], - 'Utilities': [], + 'Core utilities': [ + 'core/tracer', + 'core/logger' + ] }, navConfig: { 'Serverless Best Practices video': { @@ -46,10 +46,6 @@ module.exports = { } }, footerNavConfig: { - /*'API Reference': { - href: 'https://awslabs.github.io/aws-lambda-powertools-java/api/', - target: '_blank' - },*/ Serverless: { href: 'https://aws.amazon.com/serverless/' }, diff --git a/docs/package.json b/docs/package.json index 773c54999..6139b2c62 100644 --- a/docs/package.json +++ b/docs/package.json @@ -22,7 +22,7 @@ "gatsby-theme-apollo-docs/*/*/*/*/semver": "^4.3.2" }, "keywords": [], - "license": "MIT-0", + "license": "Apache-2.0", "repository": "https://github.com/awslabs/aws-lambda-powertools-java", "name": "aws-lambda-powertools-java", "description": "Powertools is a suite of utilities for AWS Lambda Functions that makes tracing with AWS X-Ray, structured logging and creating custom metrics asynchronously easier.", From 4f59196d84d9dabfff1688763bfa877a4e340fd5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Steve=20Houe=CC=88l?= Date: Mon, 17 Aug 2020 11:52:26 +0200 Subject: [PATCH 2/3] docs: fix logger documentation --- docs/content/core/logger.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/core/logger.mdx b/docs/content/core/logger.mdx index ecb28651d..297d8d402 100644 --- a/docs/content/core/logger.mdx +++ b/docs/content/core/logger.mdx @@ -78,7 +78,7 @@ public class App implements RequestHandler This is disabled by default to prevent sensitive info being logged. From d267bd8c06e9346441c4208b96bd63302ca535a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Steve=20Houe=CC=88l?= Date: Wed, 19 Aug 2020 09:34:17 +0200 Subject: [PATCH 3/3] docs: fixing documentation --- docs/content/core/logger.mdx | 16 ++++++---------- docs/content/core/tracer.mdx | 4 ---- 2 files changed, 6 insertions(+), 14 deletions(-) diff --git a/docs/content/core/logger.mdx b/docs/content/core/logger.mdx index 297d8d402..c9e33c68b 100644 --- a/docs/content/core/logger.mdx +++ b/docs/content/core/logger.mdx @@ -50,6 +50,11 @@ Key | Type | Example | Description **coldStart** | Boolean | true| ColdStart value. **service** | String | "payment" | Service name defined. "service_undefined" will be used if unknown **message** | String | "Collecting payment" | Log statement value. Unserializable JSON values will be casted to string +**functionName**| String | "example-powertools-HelloWorldFunction-1P1Z6B39FLU73" +**functionVersion**| String | "12" +**functionMemorySize**| String | "128" +**functionArn**| String | "arn:aws:lambda:eu-west-1:012345678910:function:example-powertools-HelloWorldFunction-1P1Z6B39FLU73" + ## Capturing context Lambda info @@ -71,7 +76,7 @@ public class App implements RequestHandler