Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions docs/content/core/logging.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,8 @@ package helloworld;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import software.amazon.lambda.logging.PowertoolsLogger;
import software.amazon.lambda.logging.PowertoolsLogging;
import software.amazon.lambda.logging.LoggingUtils;
import software.amazon.lambda.logging.Logging;
...

/**
Expand All @@ -92,7 +92,7 @@ public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatew

Logger log = LogManager.getLogger();

@PowertoolsLogging
@Logging
public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
...
}
Expand All @@ -110,8 +110,8 @@ package helloworld;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import software.amazon.lambda.logging.PowertoolsLogger;
import software.amazon.lambda.logging.PowertoolsLogging;
import software.amazon.lambda.logging.LoggingUtils;
import software.amazon.lambda.logging.Logging;
...

/**
Expand All @@ -121,7 +121,7 @@ public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatew

Logger log = LogManager.getLogger();

@PowertoolsLogging(logEvent = true)
@Logging(logEvent = true)
public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
...
}
Expand All @@ -137,8 +137,8 @@ package helloworld;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import software.amazon.lambda.logging.PowertoolsLogger;
import software.amazon.lambda.logging.PowertoolsLogging;
import software.amazon.lambda.logging.LoggingUtils;
import software.amazon.lambda.logging.Logging;
...

/**
Expand All @@ -148,18 +148,18 @@ public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatew

Logger log = LogManager.getLogger();

@PowertoolsLogging(logEvent = true)
@Logging(logEvent = true)
public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
...
PowertoolsLogger.appendKey("test", "willBeLogged");
LoggingUtils.appendKey("test", "willBeLogged");
...

...
Map<String, String> customKeys = new HashMap<>();
customKeys.put("test", "value");
customKeys.put("test1", "value1");

PowertoolsLogger.appendKeys(customKeys);
LoggingUtils.appendKeys(customKeys);
...
}
}
Expand All @@ -177,8 +177,8 @@ package helloworld;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import software.amazon.lambda.logging.PowertoolsLogger;
import software.amazon.lambda.logging.PowertoolsLogging;
import software.amazon.lambda.logging.LoggingUtils;
import software.amazon.lambda.logging.Logging;
...

/**
Expand All @@ -188,7 +188,7 @@ public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatew

Logger log = LogManager.getLogger();

@PowertoolsLogging(samplingRate = 0.5)
@Logging(samplingRate = 0.5)
public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
...
}
Expand Down
28 changes: 14 additions & 14 deletions docs/content/core/metrics.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -44,15 +44,15 @@ import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import software.amazon.cloudwatchlogs.emf.logger.MetricsLogger;
import software.amazon.cloudwatchlogs.emf.model.Unit;
import software.amazon.lambda.powertools.metrics.PowertoolsMetrics;
import software.amazon.lambda.powertools.metrics.PowertoolsMetricsLogger;
import software.amazon.lambda.powertools.metrics.Metrics;
import software.amazon.lambda.powertools.metrics.MetricsUtils;

public class PowertoolsMetricsEnabledHandler implements RequestHandler<Object, Object> {
public class MetricsEnabledHandler implements RequestHandler<Object, Object> {

MetricsLogger metricsLogger = PowertoolsMetricsLogger.metricsLogger();
MetricsLogger metricsLogger = MetricsUtils.metricsLogger();

@Override
@PowertoolsMetrics(namespace = "ExampleApplication", service = "booking")
@Metrics(namespace = "ExampleApplication", service = "booking")
public Object handleRequest(Object input, Context context) {
...
}
Expand All @@ -66,12 +66,12 @@ You can initialize Metrics anywhere in your code as many times as you need - It'
You can create metrics using `putMetric`, and manually create dimensions for all your aggregate metrics using `add_dimension`.

```java:title=Handler.java
public class PowertoolsMetricsEnabledHandler implements RequestHandler<Object, Object> {
public class MetricsEnabledHandler implements RequestHandler<Object, Object> {

MetricsLogger metricsLogger = PowertoolsMetricsLogger.metricsLogger();
MetricsLogger metricsLogger = MetricsUtils.metricsLogger();

@Override
@PowertoolsMetrics(namespace = "ExampleApplication", service = "booking")
@Metrics(namespace = "ExampleApplication", service = "booking")
public Object handleRequest(Object input, Context context) {
// highlight-start
metricsLogger.putDimensions(DimensionSet.of("environment", "prod"));
Expand Down Expand Up @@ -111,7 +111,7 @@ You can use `putMetadata` for advanced use cases, where you want to metadata as
</Note><br/>

```java:title=Handler.java
@PowertoolsMetrics(namespace = "ServerlessAirline", service = "payment")
@Metrics(namespace = "ServerlessAirline", service = "payment")
public APIGatewayProxyResponseEvent handleRequest(Object input, Context context) {
metricsLogger().putMetric("CustomMetric1", 1, Unit.COUNT);
metricsLogger().putMetadata("booking_id", "1234567890"); // highlight-line
Expand All @@ -121,28 +121,28 @@ public APIGatewayProxyResponseEvent handleRequest(Object input, Context context)

This will be available in CloudWatch Logs to ease operations on high cardinal data.

The `@PowertoolsMetrics` annotation **validates**, **serializes**, and **flushes** all your metrics. During metrics validation, if no metrics are provided no exception will be raised.
The `@Metrics` annotation **validates**, **serializes**, and **flushes** all your metrics. During metrics validation, if no metrics are provided no exception will be raised.

If metrics are provided, and any of the following criteria are not met, `ValidationException` exception will be raised:

* Minimum of 1 dimension
* Maximum of 9 dimensions

If you want to ensure that at least one metric is emitted, you can pass `raiseOnEmptyMetrics = true` to the **@PowertoolsMetrics** annotation:
If you want to ensure that at least one metric is emitted, you can pass `raiseOnEmptyMetrics = true` to the **@Metrics** annotation:

```java:title=Handler.java
@PowertoolsMetrics(raiseOnEmptyMetrics = true)
@Metrics(raiseOnEmptyMetrics = true)
public Object handleRequest(Object input, Context context) {
...
}
```

## Capturing cold start metric

You can capture cold start metrics automatically with `@PowertoolsMetrics` via the `captureColdStart` variable.
You can capture cold start metrics automatically with `@Metrics` via the `captureColdStart` variable.

```java:title=Handler.java
@PowertoolsMetrics(captureColdStart = true)
@Metrics(captureColdStart = true)
public Object handleRequest(Object input, Context context) {
...
}
Expand Down
26 changes: 13 additions & 13 deletions docs/content/core/tracing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -36,25 +36,25 @@ Resources:
The Powertools service name is used as the X-Ray namespace. This can be set using the environment variable
`POWERTOOLS_SERVICE_NAME`

To enable Powertools tracing to your function add the @PowertoolsTracing annotation to your handleRequest method or on
To enable Powertools tracing to your function add the @Tracing annotation to your handleRequest method or on
any method will capture the method as a separate subsegment automatically.

```java:title=LambdaHandler.java
public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {

@PowertoolsTracing
@Tracing
public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent input, Context context) {
businessLogic1();

businessLogic2();
}

@PowertoolsTracing
@Tracing
public void businessLogic1(){

}

@PowertoolsTracing
@Tracing
public void businessLogic2(){

}
Expand All @@ -72,7 +72,7 @@ By default this annotation will automatically record method responses and except
```java:title=HandlerWithoutCapturingResponseOrError.java
public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {

@PowertoolsTracing(captureError = false, captureResponse = false)
@Tracing(captureError = false, captureResponse = false)
public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent input, Context context) {
...
}
Expand All @@ -82,14 +82,14 @@ public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatew

Annotations are key-values indexed by AWS X-Ray on a per trace basis. You can use them to filter traces as well as to create [Trace Groups](https://aws.amazon.com/about-aws/whats-new/2018/11/aws-xray-adds-the-ability-to-group-traces/).

You can add annotations using `putAnnotation()` method from PowerTracer and it will be correctly inject for the subsegment in concern.
You can add annotations using `putAnnotation()` method from TracingUtils and it will be correctly inject for the subsegment in concern.

```java
public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {

@PowertoolsTracing
@Tracing
public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent input, Context context) {
PowerTracer.putAnnotation("annotation", "value");
TracingUtils.putAnnotation("annotation", "value");
}
}
```
Expand All @@ -98,14 +98,14 @@ public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatew

Metadata are non-indexed values that can add additional context for an operation.

You can add metadata using `putMetadata()` method from PowerTracer and it will be correctly inject for the subsegment in concern.
You can add metadata using `putMetadata()` method from TracingUtils and it will be correctly inject for the subsegment in concern.

```java
public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {

@PowertoolsTracing
@Tracing
public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent input, Context context) {
PowerTracer.putMetadata("content", "value");
TracingUtils.putMetadata("content", "value");
}
}
```
Expand All @@ -119,11 +119,11 @@ under a subsegment, or you are doing multithreaded programming. Refer examples b
public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {

public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent input, Context context) {
PowerTracer.withSubsegment("loggingResponse", subsegment -> {
TracingUtils.withSubsegment("loggingResponse", subsegment -> {
// Some business logic
});

PowerTracer.withSubsegment("localNamespace", "loggingResponse", subsegment -> {
TracingUtils.withSubsegment("localNamespace", "loggingResponse", subsegment -> {
// Some business logic
});
}
Expand Down
33 changes: 16 additions & 17 deletions docs/content/utilities/batch.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ This utility requires additional permissions to work as expected. Lambda functio

## Processing messages from SQS

You can use either **[SqsBatchProcessor annotation](#SqsBatchProcessor annotation)**, or **[PowertoolsSqs Utility API](#PowertoolsSqs Utility API)** as a fluent API.
You can use either **[SqsBatch annotation](#sqsbatch-annotation)**, or **[SqsUtils Utility API](#sqsutils-utility-api)** as a fluent API.

Both have nearly the same behaviour when it comes to processing messages from the batch:

Expand All @@ -94,18 +94,18 @@ Both have nearly the same behaviour when it comes to processing messages from th
- **1)** Delete successfully processed messages from the queue by directly calling `sqs:DeleteMessageBatch`
- **2)** Raise `SQSBatchProcessingException` to ensure failed messages return to your SQS queue

The only difference is that **PowertoolsSqs Utility API** will give you access to return from the processed messages if you need. Exception `SQSBatchProcessingException` thrown from the
The only difference is that **SqsUtils Utility API** will give you access to return from the processed messages if you need. Exception `SQSBatchProcessingException` thrown from the
utility will have access to both successful and failed messaged along with failure exceptions.

## Functional Interface SqsMessageHandler

Both [annotation](#SqsBatchProcessor annotation) and [PowertoolsSqs Utility API](#PowertoolsSqs Utility API) requires an implementation of functional interface `SqsMessageHandler`.
Both [annotation](#sqsbatch-annotation) and [SqsUtils Utility API](#sqsutils-utility-api) requires an implementation of functional interface `SqsMessageHandler`.

This implementation is responsible for processing each individual message from the batch, and to raise an exception if unable to process any of the messages sent.

**Any non-exception/successful return from your record handler function** will instruct utility to queue up each individual message for deletion.

### SqsBatchProcessor annotation
### SqsBatch annotation

When using this annotation, you need provide a class implementation of `SqsMessageHandler` that will process individual messages from the batch - It should raise an exception if it is unable to process the record.

Expand All @@ -116,13 +116,12 @@ All records in the batch will be passed to this handler for processing, even if

<Note type="warning">
You will not have accessed to the <strong>processed messages</strong> within the Lambda Handler - all processing logic will and should be performed by the implemented <code>SqsMessageHandler#process()</code> function.

</Note><br/>

```java:title=App.java
public class AppSqsEvent implements RequestHandler<SQSEvent, String> {
@Override
@SqsBatchProcessor(SampleMessageHandler.class) // highlight-line
@SqsBatch(SampleMessageHandler.class) // highlight-line
public String handleRequest(SQSEvent input, Context context) {
return "{\"statusCode\": 200}";
}
Expand All @@ -140,17 +139,17 @@ public class AppSqsEvent implements RequestHandler<SQSEvent, String> {
}
```

### PowertoolsSqs Utility API
### SqsUtils Utility API

If you require access to the result of processed messages, you can use this utility.

The result from calling <code>PowertoolsSqs#batchProcessor()</code> on the context manager will be a list of all the return values from your <code>SqsMessageHandler#process()</code> function.
The result from calling <code>SqsUtils#batchProcessor()</code> on the context manager will be a list of all the return values from your <code>SqsMessageHandler#process()</code> function.

```java:title=App.java
public class AppSqsEvent implements RequestHandler<SQSEvent, List<String>> {
@Override
public List<String> handleRequest(SQSEvent input, Context context) {
List<String> returnValues = PowertoolsSqs.batchProcessor(input, SampleMessageHandler.class); // highlight-line
List<String> returnValues = SqsUtils.batchProcessor(input, SampleMessageHandler.class); // highlight-line

return returnValues;
}
Expand All @@ -176,7 +175,7 @@ public class AppSqsEvent implements RequestHandler<SQSEvent, List<String>> {
@Override
public List<String> handleRequest(SQSEvent input, Context context) {
// highlight-start
List<String> returnValues = PowertoolsSqs.batchProcessor(input, (message) -> {
List<String> returnValues = SqsUtils.batchProcessor(input, (message) -> {
// This will be called for each individual message from a batch
// It should raise an exception if the message was not processed successfully
String returnVal = doSomething(message.getBody());
Expand All @@ -192,21 +191,21 @@ public class AppSqsEvent implements RequestHandler<SQSEvent, List<String>> {
## Passing custom SqsClient

If you need to pass custom SqsClient such as region to the SDK, you can pass your own `SqsClient` to be used by utility either for
**[SqsBatchProcessor annotation](#SqsBatchProcessor annotation)**, or **[PowertoolsSqs Utility API](#PowertoolsSqs Utility API)**.
**[SqsBatch annotation](#sqsbatch-annotation)**, or **[SqsUtils Utility API](#sqsutils-utility-api)**.

```java:title=App.java

public class AppSqsEvent implements RequestHandler<SQSEvent, List<String>> {
// highlight-start
static {
PowertoolsSqs.overrideSqsClient(SqsClient.builder()
SqsUtils.overrideSqsClient(SqsClient.builder()
.build());
}
// highlight-end

@Override
public List<String> handleRequest(SQSEvent input, Context context) {
List<String> returnValues = PowertoolsSqs.batchProcessor(input, SampleMessageHandler.class);
List<String> returnValues = SqsUtils.batchProcessor(input, SampleMessageHandler.class);

return returnValues;
}
Expand All @@ -229,23 +228,23 @@ public class AppSqsEvent implements RequestHandler<SQSEvent, List<String>> {

If you want to disable the default behavior where `SQSBatchProcessingException` is raised if there are any exception, you can pass the `suppressException` boolean argument.

**Within SqsBatchProcessor annotation**
**Within SqsBatch annotation**

```java:title=App.java
...
@Override
@SqsBatchProcessor(value = SampleMessageHandler.class, suppressException = true) // highlight-line
@SqsBatch(value = SampleMessageHandler.class, suppressException = true) // highlight-line
public String handleRequest(SQSEvent input, Context context) {
return "{\"statusCode\": 200}";
}
```

**Within PowertoolsSqs Utility API**
**Within SqsUtils Utility API**

```java:title=App.java
@Override
public List<String> handleRequest(SQSEvent input, Context context) {
List<String> returnValues = PowertoolsSqs.batchProcessor(input, true, SampleMessageHandler.class); // highlight-line
List<String> returnValues = SqsUtils.batchProcessor(input, true, SampleMessageHandler.class); // highlight-line

return returnValues;
}
Expand Down
Loading