Skip to content

Commit ea09bfc

Browse files
stevehouelstevehouel
authored
docs: Implement Logger and Tracer part (#27)
* docs: Implement Logger and Tracer part * docs: fix logger documentation * docs: fixing documentation
1 parent 290e87c commit ea09bfc

File tree

6 files changed

+193
-18
lines changed

6 files changed

+193
-18
lines changed

‎docs/content/core/logger.mdx

+142
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
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+
**functionName**| String | "example-powertools-HelloWorldFunction-1P1Z6B39FLU73"
54+
**functionVersion**| String | "12"
55+
**functionMemorySize**| String | "128"
56+
**functionArn**| String | "arn:aws:lambda:eu-west-1:012345678910:function:example-powertools-HelloWorldFunction-1P1Z6B39FLU73"
57+
58+
59+
## Capturing context Lambda info
60+
61+
You can enrich your structured logs with key Lambda context information via `logEvent` annotation parameter.
62+
63+
```java:title=App.java
64+
package helloworld;
65+
66+
import org.apache.logging.log4j.LogManager;
67+
import org.apache.logging.log4j.Logger;
68+
import software.amazon.lambda.logging.PowerLogger;
69+
import software.amazon.lambda.logging.PowerToolsLogging;
70+
...
71+
72+
/**
73+
* Handler for requests to Lambda function.
74+
*/
75+
public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
76+
77+
Logger log = LogManager.getLogger();
78+
79+
@PowerToolsLogging
80+
public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
81+
...
82+
}
83+
}
84+
```
85+
86+
You can also explicitly log any incoming event using `logEvent` param.
87+
88+
<Note type="warning">
89+
This is disabled by default to prevent sensitive info being logged.
90+
</Note><br/>
91+
92+
```java:title=App.java
93+
package helloworld;
94+
95+
import org.apache.logging.log4j.LogManager;
96+
import org.apache.logging.log4j.Logger;
97+
import software.amazon.lambda.logging.PowerLogger;
98+
import software.amazon.lambda.logging.PowerToolsLogging;
99+
...
100+
101+
/**
102+
* Handler for requests to Lambda function.
103+
*/
104+
public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
105+
106+
Logger log = LogManager.getLogger();
107+
108+
@PowerToolsLogging(logEvent = true)
109+
public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
110+
...
111+
}
112+
}
113+
```
114+
115+
## Appending additional keys
116+
117+
You can append your own keys to your existing Logger via `customKey`.
118+
119+
```java:title=App.java
120+
package helloworld;
121+
122+
import org.apache.logging.log4j.LogManager;
123+
import org.apache.logging.log4j.Logger;
124+
import software.amazon.lambda.logging.PowerLogger;
125+
import software.amazon.lambda.logging.PowerToolsLogging;
126+
...
127+
128+
/**
129+
* Handler for requests to Lambda function.
130+
*/
131+
public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
132+
133+
Logger log = LogManager.getLogger();
134+
135+
@PowerToolsLogging(logEvent = true)
136+
public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
137+
...
138+
PowerLogger.customKey("test", "willBeLogged");
139+
...
140+
}
141+
}
142+
```

‎docs/content/core/tracer.mdx

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
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+
**Key features**
11+
12+
* Support tracing async methods

‎docs/content/index.mdx

+32-8
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

+2-1
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

+4-8
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

+1-1
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)