Integrate the Node.js 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. 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

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

Before You Begin

Ensure your deployment has:

• An AWS Lambda function instrumented with the Node.js Serverless Tracer
• Active EUM licenses and JavaScript Agents

Add the EUM Environment Variable

By default, EUM integration is turned off for the Node.js Serverless Tracer. 

To enable EUM integration, set the APPDYNAMICS_ENABLE_EUM environment variable to true. See Set Up the Serverless APM Environment for more details. 

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 
• Passing directly via AWS Lambda Proxy Integration
• Returning EUM metadata in your function code

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 table below lists the required response headers and their mapping values:

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.

Response Header Mappings for All Other Invocations 

To gather EUM metadata, you need to configure response header mappings. This code sample invokes an appDEumHeaders method on the tracer. This method returns an object containing the ADRUM_n headers. Pass this object to the downstream service for consumption by the downstream JavaScript Agent.

The code snippet below demonstrates how you can return EUM metadata:

module.exports.myLambdaHandler = function (event, context, callback) {
  setTimeout(function () {
 
	////Call a transaction object
    let appDBusinessTxn = tracer.getCurrentTransaction();
 
	//Stop the transaction
    tracer.stopTransaction();
 
	//Return EUM Metadata
    let appDEumHeaders = tracer.getEumMetadata(appDBusinessTxn);
    callback(null, {
      eumMetadata: appDEumHeaders,
      data: 'Call to Lambda is a success'
    });
  }, 300);
}

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 Inject the JavaScript Agent.

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 table below lists response header mappings and example mapping values for CORS configuration:

//Return EUM Metadata
    let appDEumHeaders = tracer.getEumMetadata(appDBusinessTxn);
    let returnHeaders = {
      'Access-Control-Allow-Origin': 'http://my-saas-service.com:8000',
      'Access-Control-Allow-Credentials': true,
      'Access-Control-Expose-Headers': 'ADRUM_0,ADRUM_1,ADRUM_2,ADRUM_3'
    };

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.