Skip to content

Commit 4f608fe

Browse files
stevehouelstevehouel
committed
docs: Implement Logger and Tracer part
1 parent e69b1c7 commit 4f608fe

File tree

6 files changed

+201
-18
lines changed

6 files changed

+201
-18
lines changed

‎docs/content/core/logger.mdx

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
title: Logger
3+
description: Core utility
4+
---
5+
6+
import Note from "../../src/components/Note"
7+
8+
Logger provides an opinionated logger with output structured as JSON.
9+
10+
**Key features**
11+
12+
* Capture key fields from Lambda context, cold start and structures logging output as JSON
13+
* Log Lambda event when instructed (disabled by default)
14+
- Enable explicitly via annotation param
15+
* Append additional keys to structured log at any point in time
16+
17+
## Initialization
18+
19+
Powertools extends the functionality of Log4J. Below is an example log4j2.xml file, with the LambdaJsonLayout configured.
20+
21+
```xml
22+
<?xml version="1.0" encoding="UTF-8"?>
23+
<Configuration packages="com.amazonaws.services.lambda.runtime.log4j2">
24+
<Appenders>
25+
<Console name="JsonAppender" target="SYSTEM_OUT">
26+
<LambdaJsonLayout compact="true" eventEol="true"/>
27+
</Console>
28+
</Appenders>
29+
<Loggers>
30+
<Logger name="JsonLogger" level="INFO" additivity="false">
31+
<AppenderRef ref="JsonAppender"/>
32+
</Logger>
33+
<Root level="info">
34+
<AppenderRef ref="JsonAppender"/>
35+
</Root>
36+
</Loggers>
37+
</Configuration>
38+
```
39+
40+
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.
41+
42+
## Standard structured keys
43+
44+
Your Logger will always include the following keys to your structured logging:
45+
46+
Key | Type | Example | Description
47+
------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------
48+
**timestamp** | String | "2020-05-24 18:17:33,774" | Timestamp of actual log statement
49+
**level** | String | "INFO" | Logging level
50+
**coldStart** | Boolean | true| ColdStart value.
51+
**service** | String | "payment" | Service name defined. "service_undefined" will be used if unknown
52+
**message** | String | "Collecting payment" | Log statement value. Unserializable JSON values will be casted to string
53+
54+
## Capturing context Lambda info
55+
56+
You can enrich your structured logs with key Lambda context information via `logEvent` annotation parameter.
57+
58+
```java:title=App.java
59+
package helloworld;
60+
61+
import org.apache.logging.log4j.LogManager;
62+
import org.apache.logging.log4j.Logger;
63+
import software.amazon.lambda.logging.PowerLogger;
64+
import software.amazon.lambda.logging.PowerToolsLogging;
65+
...
66+
67+
/**
68+
* Handler for requests to Lambda function.
69+
*/
70+
public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
71+
72+
Logger log = LogManager.getLogger();
73+
74+
@PowerToolsLogging()
75+
public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
76+
...
77+
}
78+
}
79+
```
80+
81+
You can also explicitly log any incoming event using `logEvent` param or via `POWERTOOLS_LOGGER_LOG_EVENT` env var.
82+
83+
<Note type="warning">
84+
This is disabled by default to prevent sensitive info being logged.
85+
</Note><br/>
86+
87+
```java:title=App.java
88+
package helloworld;
89+
90+
import org.apache.logging.log4j.LogManager;
91+
import org.apache.logging.log4j.Logger;
92+
import software.amazon.lambda.logging.PowerLogger;
93+
import software.amazon.lambda.logging.PowerToolsLogging;
94+
...
95+
96+
/**
97+
* Handler for requests to Lambda function.
98+
*/
99+
public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
100+
101+
Logger log = LogManager.getLogger();
102+
103+
@PowerToolsLogging(logEvent = true)
104+
public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
105+
...
106+
}
107+
}
108+
```
109+
110+
When used, this will include the following keys:
111+
112+
Key | Type | Example
113+
------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------
114+
**functionName**| String | "example-powertools-HelloWorldFunction-1P1Z6B39FLU73"
115+
**functionVersion**| String | "12"
116+
**functionMemorySize**| String | "128"
117+
**functionArn**| String | "arn:aws:lambda:eu-west-1:012345678910:function:example-powertools-HelloWorldFunction-1P1Z6B39FLU73"
118+
119+
## Appending additional keys
120+
121+
You can append your own keys to your existing Logger via `customKey`.
122+
123+
```java:title=App.java
124+
package helloworld;
125+
126+
import org.apache.logging.log4j.LogManager;
127+
import org.apache.logging.log4j.Logger;
128+
import software.amazon.lambda.logging.PowerLogger;
129+
import software.amazon.lambda.logging.PowerToolsLogging;
130+
...
131+
132+
/**
133+
* Handler for requests to Lambda function.
134+
*/
135+
public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
136+
137+
Logger log = LogManager.getLogger();
138+
139+
@PowerToolsLogging(logEvent = true)
140+
public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
141+
...
142+
PowerLogger.customKey("test", "willBeLogged");
143+
...
144+
}
145+
}
146+
```

‎docs/content/core/tracer.mdx

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: Tracer
3+
description: Core utility
4+
---
5+
6+
import Note from "../../src/components/Note"
7+
8+
Tracer is an opinionated thin wrapper for [AWS X-Ray Java SDK](https://github.com/aws/aws-xray-sdk-java/).
9+
10+
![Tracer showcase](../media/tracer_utility_showcase.png)
11+
12+
**Key features**
13+
14+
* Capture cold start as annotation, and responses as well as full exceptions as metadata
15+
* Run functions locally with SAM CLI without code change to disable tracing
16+
* Support tracing async methods

‎docs/content/index.mdx

Lines changed: 32 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -21,15 +21,39 @@ Powertools is available in Maven Central. You can use your favourite dependency
2121
...
2222
</dependencies>
2323
```
24-
* [gradle](https://gradle.org/):
25-
```
26-
repositories {
27-
mavenCentral()
28-
}
2924

30-
dependencies {
31-
powertools 'software.amazon.lambda:aws-lambda-powertools-java:YOUR_REQUIRED_VERSION'
32-
}
25+
And configure the aspectj-maven-plugin to compile-time weave (CTW) the aws-lambda-powertools-java aspects into your project:
26+
27+
```xml
28+
<build>
29+
<plugins>
30+
...
31+
<plugin>
32+
<groupId>com.nickwongdev</groupId>
33+
<artifactId>aspectj-maven-plugin</artifactId>
34+
<version>1.12.1</version>
35+
<configuration>
36+
<source>1.8</source>
37+
<target>1.8</target>
38+
<complianceLevel>1.8</complianceLevel>
39+
<aspectLibraries>
40+
<aspectLibrary>
41+
<groupId>software.amazon.lambda</groupId>
42+
<artifactId>aws-lambda-powertools-java</artifactId>
43+
</aspectLibrary>
44+
</aspectLibraries>
45+
</configuration>
46+
<executions>
47+
<execution>
48+
<goals>
49+
<goal>compile</goal>
50+
</goals>
51+
</execution>
52+
</executions>
53+
</plugin>
54+
...
55+
</plugins>
56+
</build>
3357
```
3458

3559
## Tenets

‎docs/gatsby-browser.js

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@ export const onRouteUpdate = ({ location, prevLocation }) => {
88
data: {
99
url: window.location.href,
1010
section: location.pathname,
11-
previous: prevLocation ? prevLocation.pathname : null
11+
previous: prevLocation ? prevLocation.pathname : null,
12+
language: 'java'
1213
},
1314
streamName: awsconfig.aws_kinesis_firehose_stream_name
1415
}, 'AWSKinesisFirehose')

‎docs/gatsby-config.js

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,15 @@ module.exports = {
1717
menuTitle: 'Helpful resources',
1818
githubRepo: 'awslabs/aws-lambda-powertools-java',
1919
baseUrl: `${docsWebsite}`,
20-
algoliaApiKey: 'a8491b576861e819fd50d567134eb9ce',
21-
algoliaIndexName: 'aws-lambda-powertools-java',
2220
logoLink: `${docsWebsite}`,
2321
sidebarCategories: {
2422
null: [
2523
'index'
2624
],
27-
'Core utilities': [],
28-
'Utilities': [],
25+
'Core utilities': [
26+
'core/tracer',
27+
'core/logger'
28+
]
2929
},
3030
navConfig: {
3131
'Serverless Best Practices video': {
@@ -46,10 +46,6 @@ module.exports = {
4646
}
4747
},
4848
footerNavConfig: {
49-
/*'API Reference': {
50-
href: 'https://awslabs.github.io/aws-lambda-powertools-java/api/',
51-
target: '_blank'
52-
},*/
5349
Serverless: {
5450
href: 'https://aws.amazon.com/serverless/'
5551
},

‎docs/package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
"gatsby-theme-apollo-docs/*/*/*/*/semver": "^4.3.2"
2323
},
2424
"keywords": [],
25-
"license": "MIT-0",
25+
"license": "Apache-2.0",
2626
"repository": "https://github.com/awslabs/aws-lambda-powertools-java",
2727
"name": "aws-lambda-powertools-java",
2828
"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.",

0 commit comments

Comments
 (0)