Automatic Tracer Instrumentation

1. Instantiate the Tracer
2. (Optional) Override Correlation Header Method
3. Obtain a Transaction Object
4. Create External Exit Calls

Instantiate the Tracer

Automatic instantiation is compatible with RequestStreamHandler interfaces. All other interfaces require manual instantiation.

RequestStreamHandler is a predefined handler provided by AWS. See AWS documentation for more information.

To automatically instantiate the tracer:

1. Make your current handler class extend AppDynamics MonitoredRequestStreamHandler. 
2. Rename your handler class's existing method handleMonitoredRequest. 


package <MyTestPackage>;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
 
//AppDynamics tracer imports
import com.appdynamics.serverless.tracers.aws.api.AppDynamics;
import com.appdynamics.serverless.tracers.aws.api.MonitoredRequestStreamHandler;
import com.appdynamics.serverless.tracers.aws.api.ExitCall;
import com.appdynamics.serverless.tracers.aws.api.Tracer;
import com.appdynamics.serverless.tracers.aws.api.Transaction;

//Keyword extends makes MonitoredRequestStreamHanlder your project's superclass
public class <MaryHadALittleLambda> extends MonitoredRequestStreamHandler {
    
   @Override
	//Change your method to handleMonitoredRequest
    public void handleMonitoredRequest(InputStream input, OutputStream output, Context context) throws IOException {
    	}

        // Your AWS Lambda function code starts here, for example
		int letter = 0;
		while((letter = input.read()) >= 0) {
			output.write(Character.toUpperCase(letter));
        }
    }

Automatic instrumentation uses the MonitoredRequestStreamHandler class, which provides default logic to find a correlation header.  

 If you need to use a custom transport mechanism for your correlation header, you must override the tracer’s default logic in the getCorrelationHeader() method. Insert your custom logic to find the inbound correlation header so the tracer can return the inbound header.  

The code snippet demonstrates how to override the getCorrelationHeader() method: 

//(Optional)Override getCorrelationHeader(). 
//Only override if the tracer will not be able to find a correlation header using its pre-configured logic.

@Override
public String getCorrelationHeader(InputStream input, Context context) {
//Logic to find the inbound header goes here, so the inbound header can be returned
return "correlation-header";

Obtain a Transaction Object

The MonitoredRequestStreamHandler class creates a transaction for you automatically. However, you need to obtain the transaction object for use with exit calls.

The code snippet below demonstrates how to obtain the transaction object:

//Obtain your transaction for use with exit calls. 
Transaction transaction = getTransaction();

Create External Exit Calls

The createExitCall method is used to obtain an exitCall object. Exit call objects record the time spent in external exit calls and allow for correlation of downstream activity. 

Exit Call Types and Identifying Properties

In the Controller, each exit call has a distinct type, determined by a set of identifying properties. 

The exitCall types and identifying properties are listed below: 

Create an Exit Call 

Call createExitCall() on your transaction object. 

The following code sample demonstrates how you might perform an external exit call:

public void makeExitCall(URL url){
 
HttpURLConnection conn = (HttpURLConnection)url.openConnection();
 
String outgoingHeader = null;
String callType = null;
Map<String, String> identifyingProperties = new HashMap<>();
    
//Below properties are appropriate for an inter-AWS Lambda call
identifyingProperties.put("DESTINATION", functionName);
identifyingProperties.put("DESTINATION_TYPE", "LAMBDA");
callType="CUSTOM";
    
//Below properties are appropriate for an external HTTP call
identifyingProperties.put("HOST", url.getHost());     
identifyingProperties.put("PORT", String.valueOf(url.getPort()));
callType="HTTP";
 
//Define the createExitCall method to obtain an exitCall object.     
ExitCall exitCall = transaction.createExitCall(callType, identifyingProperties);
outgoingHeader =  exitCall.getCorrelationHeader();
exitCall.start();
    
try {
// Tracer.APPDYNAMICS_TRANSACTION_CORRELATION_HEADER_KEY is the name of the header that should be set
   
    if (outgoingHeader != null) {
        conn.setRequestProperty(Tracer.APPDYNAMICS_TRANSACTION_CORRELATION_HEADER_KEY, outgoingHeader); // set the correlation header on an HttpURLConnection
    }
  
// Make the exit call here
  
} finally {
        exitCall.stop();
    }
}

Making Multiple External Exit Calls

If one AWS Lambda function makes multiple exit calls, each function should be identified by a unique exitCall object. To make multiple exit calls, create new exitCall objects for each distinct exit call. The exitCall objects are not reusable.