Integrate the Java Serverless Tracer with End User Monitoring

This document contains links to AWS documentation. AppDynamics makes no representation as to the accuracy of Amazon documentation since Amazon controls its own documentation.

Serverless APM for AWS Lambda is designed to integrate with your existing End User Monitoring (EUM) configurations. The EUM integration provides complete end-to-end visibility on the performance of your web and mobile applications, linking calls from an end-user device through your serverless functions to continue your business transactions

AWS Lambda functions can correlate EUM and AWS Lambda-originated business transactions, in conjunction with the following EUM agents:

• Browser Real User Monitoring (Browser RUM)
• Mobile Real User Monitoring (Mobile RUM)
• IoT Monitoring

Integration of the Java Serverless Tracer with End User Monitoring consists of these steps: 

1. Add and Return EUM Metadata
2. Configure Response Header Mappings
   1. Use the Amazon API Gateway
   2. Use AWS Lambda Proxy Integration
3. Update the Front End Application
4. Enable CORS configuration (If applicable)
5. Troubleshoot the EUM Integration

This document assumes you are familiar with AppDynamics End User Monitoring. See End User Monitoring for more information.

Before You Begin

Ensure your deployment has:

• An AWS Lambda function instrumented with the Java Serverless Tracer
• Active EUM licenses and JavaScript agents

Add and Return EUM Metadata 

To integrate EUM with the tracer, you need to query the transaction object and return EUM metadata. 

Call the method below after stopping a transaction. Assign each string separately, in the order specified, to the headers ADRUM_0, ADRUM_1, ADRUM_2, and ADRUM_3 for consumption by the downstream JavaScript Agent.

public void stopTransactionAndRecordEUM(OutputStream output) throws IOException {
        Transaction transaction = getTransaction();
 
// Your AWS Lambda function code
 
//You must call transaction.stop(); before calling transaction.getEumMetadata();
 transaction.stop();
// call transaction.getEumMetadata(); function to query transaction object for EUM metadata  
List<String> eumMetadata = transaction.getEumMetadata();

Configure Response Header Mappings

Configure response header mappings to pass ADRUM_n headers back to the browser. You can configure response header mappings using the AWS API Gateway or pass them directly using AWS Lambda Proxy Integration.

Response Header Mappings in Amazon API Gateway

Add header mappings for each ADRUM_n header in the Amazon API Gateway. To configure response header mappings in the Amazon API Gateway, refer to the Amazon documentation.

The screenshot illustrates how to map these headers in the AWS API Gateway:

^{Amazon Web Services, the AWS logo, AWS, and any other AWS Marks used in these materials are trademarks of Amazon.com, Inc. or its affiliates in the United States and/or other countries.}

Next, return the ADRUM_n headers as part of the AWS Lambda function output. You can use another field name, as long your function code is consistent with the response header mappings. 

This code snippet shows how to add the headers field to an output object class: 

// add the field eumMetadata to your output object class
// return the EUM ADRUM_n headers in the output object
String outputString = "success";
Output outputObj = new Output(outputString);
OutputObj.eumMetadata = eumMetadata;
output.write(new Gson().toJson(outputObj).getBytes(StandardCharsets.UTF_8)); 

Response Header Mappings in AWS Lambda Proxy Integration 

As an alternative to custom integration, AWS Lambda proxy integration allows the client to call each function in the backend and returns output in a JSON format. Map these responses by adding each single-value ADRUM_n header directly to the headers field in your output object class. Refer to the Amazon documentation for details.

Update the Front End Application

To see the correlation between EUM and AWS Lambda-originated business transactions, you must inject the JavaScript Agent into your browser's HTML, as described in the EUM documentation.

Enable CORS Configuration

Browsers require cross-origin resource sharing (CORS) for functions that access responses from browser requests to a domain other than the base page's domain. You must explicitly grant cross-domain access to all applicable ADRUM_n headers. 

To enable CORS configuration, define the required AWS response headers in the Amazon API Gateway:

• Access-Control-Expose-Headers - maps the custom ADRUM headers. These headers must have the names ADRUM_0 through ADRUM_3 to be compatible with the JavaScript Agent.
• Access-Control-Allow-Methods - check the header(s) with the appropriate method.
• Access-Control-Allow-Origin - set to the full URL of the web page that originated the request, including schema, hostname, and port.

See AWS documentation for advanced headers and additional details.  

The screenshot illustrates how to enable CORS in the Amazon API Gateway:

^{Amazon Web Services, the AWS logo, AWS, and any other AWS Marks used in these materials are trademarks of Amazon.com, Inc. or its affiliates in the United States and/or other countries.}

After you have enabled CORS, you must define the response header mappings. To configure response header mappings in the Amazon API Gateway, refer to the Amazon documentation. 

The screenshot illustrates response header mappings after CORS configuration:

Troubleshoot the EUM Integration

If you do not see a correlation between EUM data and business transactions, collect an HTTP Archive (HAR) file that captures the activity in your browser. Use the HAR file to confirm all necessary CORS headers are set and expected data populates in the ARUM_n headers. 

The EUM documentation provides additional troubleshooting advice.