Skip to content

Homepage

aws provider Build status Maven Central

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.

Looking for a quick run through of the core utilities?

Check out this detailed blog post with a practical example.

Tenets

This project separates core utilities that will be available in other runtimes vs general utilities that might not be available across all runtimes.

  • AWS Lambda only – We optimise for AWS Lambda function environments and supported runtimes only. Utilities might work with web frameworks and non-Lambda environments, though they are not officially supported.
  • Eases the adoption of best practices – The main priority of the utilities is to facilitate best practices adoption, as defined in the AWS Well-Architected Serverless Lens; all other functionality is optional.
  • Keep it lean – Additional dependencies are carefully considered for security and ease of maintenance, and prevent negatively impacting startup time.
  • We strive for backwards compatibility – New features and changes should keep backwards compatibility. If a breaking change cannot be avoided, the deprecation and migration process should be clearly defined.
  • We work backwards from the community – We aim to strike a balance of what would work best for 80% of customers. Emerging practices are considered and discussed via Requests for Comment (RFCs)
  • Idiomatic – Utilities follow programming language idioms and language-specific best practices.

Install

Powertools dependencies are available in Maven Central. You can use your favourite dependency management tool to install it

Quick hello world examples using SAM CLI

You can use SAM to quickly setup a serverless project including AWS Lambda Powertools Java.

1
  sam init --location gh:aws-samples/cookiecutter-aws-sam-powertools-java

For more information about the project and available options refer to this repository

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
<dependencies>
    ...
    <dependency>
        <groupId>software.amazon.lambda</groupId>
        <artifactId>powertools-tracing</artifactId>
        <version>1.7.3</version>
    </dependency>
    <dependency>
        <groupId>software.amazon.lambda</groupId>
        <artifactId>powertools-logging</artifactId>
        <version>1.7.3</version>
    </dependency>
    <dependency>
        <groupId>software.amazon.lambda</groupId>
        <artifactId>powertools-metrics</artifactId>
        <version>1.7.3</version>
    </dependency>
    ...
</dependencies>
...
<!-- configure the aspectj-maven-plugin to compile-time weave (CTW) the aws-lambda-powertools-java aspects into your project -->
<build>
    <plugins>
        ...
        <plugin>
             <groupId>org.codehaus.mojo</groupId>
             <artifactId>aspectj-maven-plugin</artifactId>
             <version>1.14.0</version>
             <configuration>
                 <source>1.8</source>
                 <target>1.8</target>
                 <complianceLevel>1.8</complianceLevel>
                 <aspectLibraries>
                     <aspectLibrary>
                         <groupId>software.amazon.lambda</groupId>
                         <artifactId>powertools-tracing</artifactId>
                     </aspectLibrary>
                     <aspectLibrary>
                         <groupId>software.amazon.lambda</groupId>
                         <artifactId>powertools-logging</artifactId>
                     </aspectLibrary>
                     <aspectLibrary>
                         <groupId>software.amazon.lambda</groupId>
                         <artifactId>powertools-metrics</artifactId>
                     </aspectLibrary>
                 </aspectLibraries>
             </configuration>
             <executions>
                 <execution>
                     <goals>
                         <goal>compile</goal>
                     </goals>
                 </execution>
             </executions>
        </plugin>
        ...
    </plugins>
</build>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
plugins{
    id 'java'
    id 'aspectj.AspectjGradlePlugin' version '0.0.6'
}
repositories {
    jcenter()
}
dependencies {
    implementation 'software.amazon.lambda:powertools-tracing:1.7.3'
    aspectpath 'software.amazon.lambda:powertools-tracing:1.7.3'
    implementation 'software.amazon.lambda:powertools-logging:1.7.3'
    aspectpath 'software.amazon.lambda:powertools-logging:1.7.3'
    implementation 'software.amazon.lambda:powertools-metrics:1.7.3'
    aspectpath 'software.amazon.lambda:powertools-metrics:1.7.3'
}
Note:

Please add aspectjVersion = '1.9.6' to the gradle.properties file. The aspectj plugin works at the moment with gradle 5.x only if you are using java 8 as runtime. Please refer to open issue for more details.

Environment variables

Info

Explicit parameters take precedence over environment variables.

Environment variable Description Utility
POWERTOOLS_SERVICE_NAME Sets service name used for tracing namespace, metrics dimension and structured logging All
POWERTOOLS_METRICS_NAMESPACE Sets namespace used for metrics Metrics
POWERTOOLS_LOGGER_SAMPLE_RATE Debug log sampling Logging
POWERTOOLS_LOG_LEVEL Sets logging level Logging
POWERTOOLS_TRACER_CAPTURE_RESPONSE Enables/Disables tracing mode to capture method response Tracing
POWERTOOLS_TRACER_CAPTURE_ERROR Enables/Disables tracing mode to capture method error Tracing

Last update: 2021-09-14