On this page:


Related Pages

This section provides examples that describe how common use cases for the Agent API can be implemented.  For reference information, see the javadoc at https://sdkdocs.appdynamics.com/javadocs/java-agent-api/v4.5/.

Common Use Cases

The following are the common use cases for the Agent API.

Starting and Ending a Synchronous Business Transaction

The following example shows code that starts a Business Transaction called 'Checkout' whenever the method checkout() is called. The Business Transaction ends when the method returns. Encapsulating the method body in a try or finally block ensures that you end the Business Transaction even if the method itself throws an exception or otherwise terminates without reaching the end.

public String checkout(List<ItemOrders> orders) {
   Transaction transaction = null;
   try {
        transaction = AppdynamicsAgent.startTransaction("Checkout", null, EntryTypes.POJO, false);
 
        /*******************
         * Method Body Here
         *******************/
    } finally {
        if (transaction != null) {
           transaction.end();
        }
    }
}
CODE


Alternatively, you can use try-with-resources pattern:

public String checkout(List<ItemOrders> orders) {
   try (Transaction transaction = AppdynamicsAgent.startTransaction("Checkout", null, EntryTypes.POJO, false)) {
        /*******************
         * Method Body Here
         *******************/
    }
}
CODE

In this case, the Business Transaction ends when the try block closes.

Starting and Ending an Asynchronous Business Transaction

This example shows code that starts a Business Transaction called 'CheckoutAsync' whenever the method checkoutAsync() is called.  The originating segment created for the Business Transaction ends when the method endSegment() is called on the Business Transaction, or when it is closed if used in a try-with-resources construct.  Encapsulating the method body in a try/finally block ensures that we end the segment even if the method itself throws an exception or otherwise terminates without reaching the end.

//The thread where the Business Transaction starts
public String checkoutAsync(List<ItemOrders> orders) {
   Transaction transaction = null;
   try {
        transaction = AppdynamicsAgent.startTransaction("CheckoutAsync", null, EntryTypes.POJO, true);
		//mark handoff to link this segment with the end segment
		transaction.markHandoff(commonPayload);

        /*******************
         * Method Body Here
         *******************/
    } finally {
        if (transaction != null) {
           transaction.endSegment();
        }
    }
}
CODE


Alternatively, the try-with-resources pattern is supported:

//The thread where the Business Transaction starts
public String checkoutAsync(List<ItemOrders> orders) {
   try (Transaction transaction = AppdynamicsAgent.startTransaction("CheckoutAsync", null, EntryTypes.POJO, true)) {
		//mark handoff to link this segment with the end segment
		transaction.markHandoff(commonPayload);

        /*******************
         * Method Body Here
         *******************/
    }
}
CODE


This ends the segment in the thread where the Business Transaction was started when the try block closes. The Business Transaction itself needs to be ended in the method where the asynchronous Business Transaction ends:

//The thread where the Business Transaction ends
public String checkoutAsyncEnd(List<ItemOrders> orders, Transaction transaction, Object commonPayload) {
   //link to the originating segment
   Transaction transactionSegment = AppdynamicsAgent.startSegment(commonPayload);

   /*******************
   * Method Body Here
   *******************/
   if (transactionSegment != null) {
      transactionSegment.endSegment();
   }
   if (transaction != null) {
      transaction.end();
   }
}
CODE

Setting the Transaction Name After a Start

The following example shows how to set the transaction name after it has been started. This is useful if you want to split transactions based on events that happen in your application:

Transaction name can only be set after a start on the originating segment, and if no async hand-offs or exits have been made.

public String checkout(List<ItemOrders> orders) {
   AppdynamicsAgent.startTransaction("Checkout", null, EntryTypes.POJO, false);
   /*******************
    * Method Body Here
    *******************/
   if (orders.isEmpty()) {
   	   AppdynamicsAgent.setCurrentTransactionName("Empty Cart");
   }
   AppdynamicsAgent.getTransaction().end();
}
CODE

Starting a Transaction Using OOTB Servlet Naming Rules

The following example shows how to leverage automatic servlet naming rules to name a transaction:

public String checkout(List<ItemOrders> orders) {
	Map<String, String> headers = new HashMap<String, String>();
	headers.put("header1", "headerValue1");
	Map<String, String[]> parameters = new HashMap<String, String[]>();
	Map<String, Object> cookies = new HashMap<String, Object>();
	cookies.put("chip", "ahoy");
	ServletContext.ServletContextBuilder contextBuilder = new ServletContext.ServletContextBuilder()
        .withURL(new URL("https://www.yourstore.com/endpoint/to/checkout"))
        .withParameters(parameters)
        .withHeaders(headers)
        .withCookies(cookies)
        .withSessionAttributes(new HashMap<String, Object>())
        .withRequestMethod("GET")
        .withHostValue("hostValue")
        .withHostOriginatingAddress("hostOriginatingAddress");
	Transaction t = AppdynamicsAgent.startServletTransaction(contextBuilder.build(), EntryTypes.HTTP, null, false);
   /*******************
    * Method Body Here
    *******************/
   t.end();
}
CODE

Defining an Exit Call

For an inventoryServer.verifyQuantities(orders), which makes a request to another process, you can monitor that request as an Exit Call. This helps to continue monitoring the Business Transaction through the call to the downstream server and identify the time spent in the remote service. You can do this by modifying the method as follows:

public void verifyQuantities(List<ItemOrders> orders) {
    ExitCall exitCall = null;
    try {
        exitCall = AppdynamicsAgent.getTransaction().startExitCall("Quantity Check", "Inventory Server", ExitTypes.HTTP, false);
         
       /*******************
        * Method Body
        *******************/
    } finally {
        if (exitCall != null) {
            exitCall.end();
        }
    }
}
CODE


The above code modifications define the Exit Call that manifests it as a remote service in the controller.  To tag and follow the request into an instrumented downstream tier, add a correlation header:

public void verifyQuantities(List<ItemOrders> orders) {
    ExitCall exitCall = null;
    try {
        exitCall = AppdynamicsAgent.getTransaction().startExitCall("Quantity Check", "Inventory Server", ExitTypes.HTTP, false);
 
        // Generate the appdynamics correlation header
        String correlationHeader = exitCall.getCorrelationHeader();
 
        // ... Method code including request creation
 
        // Modify the request/payload to include the correlation header
        inventoryRequest.addHeader(AppdynamicsAgent.TRANSACTION_CORRELATION_HEADER, correlationHeader);
     
    } finally {
        if (exitCall != null) {
            exitCall.end();
        }
    }
}
CODE

Defining an Asynchronous Thread Handoff

If your checkout method also does a thread handoff and executes some business logic that you want to monitor in a separate thread, register the worker thread with the Business Transaction:

public String checkout(List<ItemOrders> orders) {
    Transaction transaction = null;
    try {
        transaction = AppdynamicsAgent.startTransaction("Checkout", null, EntryTypes.POJO, false);
 
        // ... Method code
 
        // Custom thread handoff using custom queue
        asyncTaskQueue.add(task);
         
    } finally {
        if (transaction != null) {
           transaction.end();
        }
    }
}
CODE


To instrument this, modify the add method to mark a thread handoff and then start a new segment where the thread begins running:

public class AsyncTaskQueue {
    public void add(Task task) {
        AppdynamicsAgent.getTransaction().markHandoff(task);
         
        /*******************
         * Method Body
         *******************/
}
CODE 
public class Task {
    public void run() {
        Transaction transaction = null;
        try {
            transaction = AppdynamicsAgent.startSegment(this);
 
            /*******************
             * Method Body
             *******************/
        } finally {
            if (transaction != null) {
                transaction.endSegment();
            }
        }
    }
 
    public void cancel() {
        AppdynamicsAgent.cancelHandoff(this);
 
        /*******************
         * Method Body
         *******************/
    }
}
CODE


The task object is used by the agent to link the segments. Correlating thread segments using the agent API requires that the agent is running in the Executor mode.

Adding Data to Snapshot or Analytics

In many instances, there are values of interest in the code that are helpful to add to the snapshot. This aids in the root cause diagnosis of issues or to send to the AppDynamics Business Transaction analytics to help answer real-time business-oriented questions about your application.  Data reported using this API appears in the same way as it had been collected with a Method Invocation Data collector.

To report a total checkout amount to Business Transaction analytics and have it presented in the APM snapshots, use the following code:

private static final Set<DataScope> dataScopeSet = new HashSet(Arrays.asList(DataScope.ANALYTICS, DataScope.SNAPSHOTS));
 
public String checkout(List<ItemOrders> orders) {
    Transaction transaction = null;
    try {
        transaction = AppdynamicsAgent.startTransaction("Checkout", null, EntryTypes.POJO, false);
 
        // ... Method code
 
        double shoppingCartTotal = total(orders);
        transaction.collectData("cart total", Double.toString(shoppingCartTotal), dataScopeSet);
         
    } finally {
        if (transaction != null) {
           transaction.end();
        }
    }
}
CODE

Defining a Custom Metric or Event

It can also be useful to report a value as a custom metric:

public String checkout(List<ItemOrders> orders) {
 
    // ... Method code
 
    double shoppingCartTotal = total(orders);
    AppdynamicsAgent.getMetricPublisher().reportSumMetric("Cart Total", (long) shoppingCartTotal);
 
}
CODE


Reporting custom metrics and events is possible irrespective of the Business Transaction context.