AWS Distro for OpenTelemetry Lambda Support For Java

The AWS managed Lambda layer for ADOT Java provides a plug-and-play user experience by wrapping an AWS Lambda function, and by packaging the OpenTelemetry Java SDK together with an out-of-the-box configuration for AWS Lambda and AWS X-Ray. Users can enable and disable OpenTelemetry for their Lambda function without changing code.

With the ADOT Lambda Layer for Java, the wrapper has built-in support for instrumenting the AWS SDK automatically. For additional instrumenting functionality, see the documentation on auto-instrumentation for traces.

Requirements

The Lambda layer supports Java 8 and 11 Lambda runtimes. For more information about supported Java versions, see the OpenTelemetry Java documentation.

Add the ARN of the Lambda Layer

In this section, we consume the Lambda layer for use with Java Lambda Functions. This includes a reduced version of the AWS Distro for OpenTelemetry Collector (ADOT Collector), which runs as a Lambda extension.

Note: Lambda layers are a regionalized resource, meaning that they can only be used in the Region in which they are published. Make sure to use the layer in the same region as your Lambda functions.

Find the supported regions and amd64/arm64 layer ARN in the table below for the ARNs to consume. Use amd64 as architecture for x86-based processors.

Enable auto-instrumentation for your Lambda function

To enable the AWS Distro for OpenTelemetry in your Lambda function, you need to add and configure the layer, and then enable tracing.

1. Open the Lambda function you intend to instrument in the AWS console.
2. In the Layers in Designer section, choose Add a layer.
3. Under specify an ARN, paste the layer ARN, and then choose Add.
4. Add the environment variable AWS_LAMBDA_EXEC_WRAPPER and set it to one of the following options:
   1. /opt/otel-handler - for wrapping regular handlers (implementing RequestHandler)
   2. /opt/otel-proxy-handler - for wrapping regular handlers (implementing RequestHandler) proxied through API Gateway, enabling HTTP context propagation
   3. /opt/otel-stream-handler - for wrapping streaming handlers (implementing RequestStreamHandler), enabling HTTP context propagation for HTTP requests
   4. /opt/otel-sqs-handler - for wrapping SQS-triggered function handlers (implementing RequestHandler)
5. Enable active tracing for your AWS Lambda function.

Tips:

• By default, the layer is configured to export traces to AWS X-Ray. Make sure your Lambda role has the required AWS X-Ray permissions. See more on AWS X-Ray permissions for AWS Lambda, see the AWS Lambda documentation.

Note: Inside the Java-Wrapper layer only the 1 kind of APIGW (APIGatewayProxyRequestEvent) event object is currently supported. The issue is currently being tracked here

Enable additional instrumentation

AWS SDK instrumentation is included and loaded automatically if you use the AWS SDK.

However, for any other library, you will need to include the corresponding library instrumentation from the OpenTelemetry instrumentation repository and modify your code to initialize it in your function. See the README.MD file for each library for additional information.

You can see an example with OKHttp in the OpenTelemetry Lambda sample application.

Remove OpenTelemetry from your Lambda function

To disable OpenTelemetry for your Lambda function, remove the Lambda layer, remove the environment variable AWS_LAMBDA_EXEC_WRAPPER, and disable active tracing, as explained in the section above.

Configuration

The AWS Lambda layer for ADOT Java combines both the ADOT Java SDK and the ADOT Collector. The configuration of the ADOT Collector follows the OpenTelemetry standard.

By default, the ADOT Lambda layer uses the config.yaml, which exports telemetry data to AWS X-Ray. To customize the Collector config, see the main Lambda section for custom configuration instructions

Additional Instrumentation

For additional instrumentation, see the OpenTelemetry Java documentation.