Instrumenting Java Serverless Applications

Instrumenting Java Serverless Applications

Required setup

If not already configured:

After you have installed the AWS integration and the Datadog Forwarder, follow these steps to instrument your application to send enhanced Lambda metrics, logs, and traces to Datadog. To fully instrument your serverless application with distributed tracing, your Java Lambda functions must be using the Java 8 Corretto (java8.al2) or Java 11 (java11) runtimes.

Configuration

Install

Install the Datadog Lambda Library locally by adding one of the following code blocks into your pom.xml or build.gradle as appropriate based on your project’s configuration. Replace VERSION below with the latest release (omitting the preceeding v): Maven Cental

Include the following dependency in your pom.xml:

<dependency>
  <groupId>com.datadoghq</groupId>
  <artifactId>datadog-lambda-java</artifactId>
  <version>VERSION</version>
</dependency>

Include the following in your build.gradle:

dependencies {
  implementation 'com.datadoghq:datadog-lambda-java:VERSION'
}

Instrument

Follow these steps to instrument the function:

  1. Install the Datadog Lambda Layer on your function. The latest VERSION is 3.

    arn:aws:lambda:<AWS_REGION>:464622532012:layer:dd-trace-java:<VERSION>
    
  2. Configure the following environment variables on your function:

    JAVA_TOOL_OPTIONS: -javaagent:"/opt/java/lib/dd-java-agent.jar"
    DD_LOGS_INJECTION: true
    DD_JMXFETCH_ENABLED: false
    DD_TRACE_ENABLED: true
    
  3. Wrap your Lambda handler function using the wrapper provided by the Datadog Lambda Library:

    public class Handler implements RequestHandler<APIGatewayV2ProxyRequestEvent, APIGatewayV2ProxyResponseEvent> {
        public Integer handleRequest(APIGatewayV2ProxyRequestEvent request, Context context){
            DDLambda ddl = new DDLambda(request, context); //Required to initialize the trace
    
            do_some_stuff();
            make_some_http_requests();
    
            ddl.finish(); //Required to finish the active span.
            return new ApiGatewayResponse();
        }
    }
    

Subscribe

Subscribe the Datadog Forwarder Lambda function to each of your function’s log groups, in order to send metrics, traces and logs to Datadog.

  1. Install the Datadog Forwarder if you haven’t.
  2. Subscribe the Datadog Forwarder to your function’s log groups.

Monitor Java Lambda function cold starts

Cold starts occur when your serverless applications receive sudden increases in traffic, including when the function was previously inactive or when it was receiving a relatively constant number of requests. Users may perceive cold starts as slow response times or lag. Datadog highly recommends you configure a monitor on Java Lambda function cold starts, and use Datadog Serverless Insights to keep cold starts to a minimum.

To create a Datadog monitor on Java Lambda function cold starts, follow the monitor creation steps with the following criteria:

  • Metric Name: aws.lambda.enhanced.invocations
  • From: runtime:java* and cold_start:true
  • Alert Grouping: Multi Alert, trigger a separate alert for each function_arn

Tag

Although it’s optional, Datadog highly recommends tagging you serverless applications with the env, service, and version tags following the unified service tagging documentation.

Explore

After configuring your function following the steps above, view your metrics, logs, and traces on the Serverless homepage.

Monitor custom business logic

If you would like to submit a custom metric, see the sample code below:

public class Handler implements RequestHandler<APIGatewayV2ProxyRequestEvent, APIGatewayV2ProxyResponseEvent> {
    public Integer handleRequest(APIGatewayV2ProxyRequestEvent request, Context context){
        DDLambda ddl = new DDLambda(request, context);

        Map<String,Object> myTags = new HashMap<String, Object>();
            myTags.put("product", "latte");
            myTags.put("order","online");
        
        // Submit a custom metric
        ddl.metric(
            "coffee_house.order_value", // Metric name
            12.45,                      // Metric value
            myTags);                    // Associated tags

        URL url = new URL("https://example.com");
        HttpURLConnection hc = (HttpURLConnection)url.openConnection();
        hc.connect();

        ddl.finish();
    }
}

See the custom metrics documentation for more information on custom metric submission.

Connect logs and traces

To automatically connect Java Lambda function logs and traces, see Connecting Java Logs and Traces for instructions.

Failing to use the correct Java runtime can result in errors like, "Error opening zip file or JAR manifest missing : /opt/java/lib/dd-java-agent.jar" Make sure to use java8.al2 or java11 as runtime as described above.

Further Reading