diff --git a/docs/content/core/logger.mdx b/docs/content/core/logger.mdx new file mode 100644 index 000000000..c9e33c68b --- /dev/null +++ b/docs/content/core/logger.mdx @@ -0,0 +1,142 @@ +--- +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 +**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 + +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. + + + 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) { + ... + } +} +``` + +## 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..daeb3557c --- /dev/null +++ b/docs/content/core/tracer.mdx @@ -0,0 +1,12 @@ +--- +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/). + +**Key features** + +* 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.",