Skip to main content

AWS Lambda - Java function instrumentation

This document covers how to install and configure OpenTelemetry distributed tracing for AWS Lambda functions based on Java and send the data to Sumo Logic.

Requirements​

You can instrument your AWS Java Lambda function using the Sumo Logic AWS distro Lambda layer. By default calls to the Lambda function and AWS Services are instrumented, see the Manual Instrumentation section below if your function is performing some other calls like HTTP requests or database calls.

You'll need the following:

  • Java8 (Corretto) or Java11 (Corretto)
  • Lambda layers add permissions
  • HTTP Traces Source endpoint URL - To send spans from the instrumented Lambda function to Sumo Logic you need an endpoint URL from an existing or new HTTP Traces Source.

Sumo Logic AWS Distro Lambda Layer supports:

  • Java8 (Corretto) and Java11 (Corretto)
  • x86_64 and arm64 architectures

Sumo Logic AWS Distro Lambda layer ​

  1. Navigate to functions in the AWS Lambda Console and open the function you want to instrument.

  2. Navigate to the Layers section and click Add a layer.

  3. In the Choose a layer menu, select Specify an ARN and paste the ARN ID for your Lambda function AWS Region. Reference the amd64 and arm64 tables for the ARN ID.

    lambda-java1.png

  4. Ensure the AWS Distro layer is present in the Layers section:

    lambda-java2.png

  5. Navigate to the Configuration > Environment variables section and set up the following required environment variables:

    • AWS_LAMBDA_EXEC_WRAPPER environment variable configures the appropriate wrapper for a specific type of lambda handler function. Set the value appropriate for your handler:

      • /opt/otel-handler - if implementing RequestHandler
      • /opt/otel-proxy-handler - if implementing RequestHandler but proxied through API Gateway
      • /opt/otel-stream-handler - if implementing RequestStreamHandler

    • OTEL_SERVICE_NAME = YOUR_SERVICE_NAME - Ensure you define it as a string value that represents the function name and its business logic such as "Check SQS Lambda". This will appear as the tracing service name in Sumo Logic.

    • Tracing application and cloud.account.id are set with the OTEL_RESOURCE_ATTRIBUTES environment variable.

      • application=YOUR_APPLICATION_NAME - the string value, if the function is a part of complex system/application then set it for all other functions/applications.

      • cloud.account.id=YOUR_CLOUD_ACCOUNT_ID - set an additional tag that will contain your AWS Lambda Account ID. This will help to provide more relevant data. 

        All of the attributes above are comma separated key/value pairs (this is also a way to add additional information to the spans, just after comma add additional key=value pair) such as, OTEL_RESOURCE_ATTRIBUTES=application=YOUR_APPLICATION_NAME,cloud.account.id=123456789012.

      • SUMOLOGIC_HTTP_TRACES_ENDPOINT_URL has to be set to send all gathered telemetry data to Sumo Logic. The URL comes from an HTTP Traces Endpoint URL. You can use an existing Source or create a new one if needed.

      img

  6. Your function should be successfully instrumented. Invoke the function and find your traces in the Sumo Logic Tracing screen.

Optional manual instrumentation​

By default, only calls to the Lambda function and AWS Services are instrumented to decrease instrumentation overhead. If the Lambda function is performing some other calls like HTTP requests or database calls it's worth providing additional instrumentation to get a better understanding of the Lambda execution.

See the OpenTelemetry Java Instrumentation repository and check if they are on the list of supported packages. Some changes in the code are needed and the specific package will have to be added to the Lambda function dependencies. The steps below show how to instrument calls from the OkHttp library.

  1. Add the OkHttp instrumentation package to your Lambda function dependencies.

  2. Update the imports list, add:

    import io.opentelemetry.instrumentation.okhttp.v3_0.OkHttpTracing;
    import io.opentelemetry.api.GlobalOpenTelemetry;

  3. Initialize tracing for the OkHttp library.

    okHttpClient client =
                new OkHttpClient.Builder()
    .addInterceptor(OkHttpTracing.create(GlobalOpenTelemetry.get()).newInterceptor())
        .build();

This will generate all the spans related to the calls made by the OkHttp library.

amd64 architecture​

The following are Sumo Logic AWS Distro Lambda layers for AWS Region amd64 (x86_64) architecture.

AWS RegionARN
US East (N.Virginia) us-east-1arn:aws:lambda:us-east-1:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
US East (Ohio) us-east-2arn:aws:lambda:us-east-2:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
US West (N.Carolina) us-west-1arn:aws:lambda:us-west-1:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
US West (Oregon) us-west-2arn:aws:lambda:us-west-2:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Africa (Cape Town) af-south-1arn:aws:lambda:af-south-1:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Asia Pacific (Hong Kong) ap-east-1arn:aws:lambda:ap-east-1:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Asia Pacific (Mumbai) ap-south-1arn:aws:lambda:ap-south-1:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Asia Pacific (Osaka) ap-northeast-3arn:aws:lambda:ap-northeast-3:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Asia Pacific (Seoul) ap-northeast-2arn:aws:lambda:ap-northeast-2:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Asia Pacific (Singapore) ap-southeast-1arn:aws:lambda:ap-southeast-1:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Asia Pacific (Sydney) ap-southeast-2arn:aws:lambda:ap-southeast-2:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Asia Pacific (Tokyo) ap-northeast-1arn:aws:lambda:ap-northeast-1:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Canada (Central) ca-central-1arn:aws:lambda:ca-central-1:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Europe (Frankfurt) eu-central-1arn:aws:lambda:eu-central-1:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Europe (Ireland) eu-west-1arn:aws:lambda:eu-west-1:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Europe (London) eu-west-2arn:aws:lambda:eu-west-2:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Europe (Milan) eu-south-1arn:aws:lambda:eu-south-1:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Europe (Paris) eu-west-3arn:aws:lambda:eu-west-3:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Europe (Stockholm) eu-north-1arn:aws:lambda:eu-north-1:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
Middle East (Bahrain) me-south-1arn:aws:lambda:me-south-1:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1
South America (Sao Paulo) sa-east-1arn:aws:lambda:sa-east-1:663229565520:layer:sumologic-otel-java-x86_64-ver-1-12-1:1

arm64 architecture​

The following are Sumo Logic AWS Distro Lambda layers for AWS Region arm64 architecture.

AWS RegionARN
US East (N.Virginia) us-east-1arn:aws:lambda:us-east-1:663229565520:layer:sumologic-otel-java-arm64-ver-1-12-1:1
US East (Ohio) us-east-2arn:aws:lambda:us-east-2:663229565520:layer:sumologic-otel-java-arm64-ver-1-12-1:1
US West (Oregon) us-west-2arn:aws:lambda:us-west-2:663229565520:layer:sumologic-otel-java-arm64-ver-1-12-1:1
Asia Pacific (Mumbai) ap-south-1arn:aws:lambda:ap-south-1:663229565520:layer:sumologic-otel-java-arm64-ver-1-12-1:1
Asia Pacific (Osaka) ap-northeast-3arn:aws:lambda:ap-northeast-3:663229565520:layer:sumologic-otel-java-arm64-ver-1-12-1:1
Asia Pacific (Singapore) ap-southeast-1arn:aws:lambda:ap-southeast-1:663229565520:layer:sumologic-otel-java-arm64-ver-1-12-1:1
Asia Pacific (Sydney) ap-southeast-2arn:aws:lambda:ap-southeast-2:663229565520:layer:sumologic-otel-java-arm64-ver-1-12-1:1
Asia Pacific (Tokyo) ap-northeast-1arn:aws:lambda:ap-northeast-1:663229565520:layer:sumologic-otel-java-arm64-ver-1-12-1:1
Europe (Frankfurt) eu-central-1arn:aws:lambda:eu-central-1:663229565520:layer:sumologic-otel-java-arm64-ver-1-12-1:1
Europe (Ireland) eu-west-1arn:aws:lambda:eu-west-1:663229565520:layer:sumologic-otel-java-arm64-ver-1-12-1:1
Europe (London) eu-west-2arn:aws:lambda:eu-west-2:663229565520:layer:sumologic-otel-java-arm64-ver-1-12-1:1

Sumo Logic AWS OTel Lambda container instrumentation​

Sumo Logic AWS OTel Lambda also provides packed OpenTelemetry Java libraries for container-based Lambda functions.

note

The instructions below support only AWS Base Images for Lambda.

Requirements​

Instrumentation of container-based AWS Lambda function requires some changes in the Dockerfile and image rebuild. You'll need the following:

  • Docker
  • Java 1.8+
  • HTTP Traces Source endpoint URL
    • To send spans from the instrumented Lambda function to Sumo Logic, you'll need an endpoint URL from an HTTP Traces Source.

Lambda function image changes​

  1. Download and extract Sumo Logic AWS OTel Lambda archive with instrumentation packages specific for your architecture, amd64 (x86_64) or arm64.
  2. Extracted instrumentation libraries have to be added to the image in /opt directory. See the Dockerfile example:
    FROM public.ecr.aws/lambda/java:11-arm64
    # Lambda Function Code
    COPY lambda-function-.jar /opt/java/lib/
    # Copy OT Instrumentation
    COPY collector-config/ /opt/collector-config/
    COPY extensions/ /opt/extensions/
    COPY java/ /opt/java/
    COPY otel-handler /opt/
    COPY otel-proxy-handler /opt/
    COPY otel-stream-handler /opt/
    CMD ["your.lambda.function.RequestHandler::lambdaHandler"]
  3. Rebuild the Docker image.

Deployment​

  1. Navigate to functions in the AWS Lambda Console and open the function you want to instrument.
  2. Deploy new function image.
  3. Navigate to the Configuration > Environment variables section and set up the following environment variables:
    • AWS_LAMBDA_EXEC_WRAPPER environment variable configures the appropriate wrapper for a specific type of lambda handler function. Set the value appropriate for your handler:
      • /opt/otel-handler - if implementing RequestHandler
      • /opt/otel-proxy-handler - if implementing RequestHandler but proxied through API Gateway
      • /opt/otel-stream-handler - if implementing RequestStreamHandler
    • OTEL_SERVICE_NAME = YOUR_SERVICE_NAME - Ensure you define it as a string value that represents the function name and its business logic such as "Check SQS Lambda". This will appear as the tracing service name in Sumo Logic.
    • OTEL_TRACES_SAMPLER = always_on - enables traces sampling
    • Tracing application and cloud.account.id are set with the OTEL_RESOURCE_ATTRIBUTES environment variable.
      • application=YOUR_APPLICATION_NAME - the string value, if the function is a part of complex system/application then set it for all other functions/applications.
      • cloud.account.id=YOUR_CLOUD_ACCOUNT_ID - set an additional tag that will contain your AWS Lambda Account ID. This will help to provide more relevant data. All of the attributes above are comma separated key/value pairs (this is also a way to add additional information to the spans, just after comma add additional key=value pair) such as, OTEL_RESOURCE_ATTRIBUTES=application=YOUR_APPLICATION_NAME,cloud.account.id=123456789012.
    • SUMOLOGIC_HTTP_TRACES_ENDPOINT_URL has to be set to send all gathered telemetry data to Sumo Logic. The URL comes from an HTTP Traces Endpoint URL. You can use an existing Source or create a new one if needed.
      otel
  4. Your function should be successfully instrumented. Invoke the function and find your traces in the Sumo Logic Tracing screen. The instructions above instrument only requests related to the handler function. To instrument other calls like HTTP calls, DB calls additional libraries have to be added to the Docker image. See supported libraries, frameworks and application servers.
Legal
Privacy Statement
Terms of Use

Copyright © 2023 by Sumo Logic, Inc.