On this page:
This topic introduces the Java Agent API and describes the common use cases for the API.
About the Java Agent API
AppDynamics automatically detects an application activity out-of-the-box. The agent ships with out-of-the-box configuration that - for supported application frameworks - tells it where Business Transaction activity starts, where thread handoffs happen and where calls to downstream systems are made and how to inject correlation headers into outbound messages and retrieve them from inbound messages such that AppDynamics can establish the end to end transaction flow through the application architecture.
For frameworks that do not benefit from out-of-the-box support, the agent provides a set of APIs allowing the application developer to make code changes to add calls to the agent to allow it to identify and follow Business Transactions as they execute, providing end-to-end visibility for any application.
Use of the agent API can be seamlessly combined with the out-of-the-box instrumentation to support situations where a mixture of supported and unsupported frameworks are in use (for example, a standard servlet making an external call using a proprietary API).
The Java Agent API enables you to programatically:
- Define Business Transactions
- Define Exit Calls
- Inform the agent when the application hands off transaction processing between threads
- Add application data to snapshots or transaction analytics
- Report custom metrics
When instrumenting any application, the agent API design prioritises the success of the application transactions over instrumentation. For this reason, if any of the agent API calls fail, they do not throw exceptions disrupting the transaction flow, but rather log messages to aid diagnosis. This also means that there is no hard dependency between the application and the presence of the AppDynamics Java agent within the JVM.
Installing the Dependency
The agent API jar can be accessed directly or downloaded from Maven Central, or it can be downloaded from the AppDynamics portal. The library version changes with each new API release, and is not tightly coupled to the version of the underlying agent, which must be a minimum of version 4.5.11.
For use with Maven Central, add the dependency to your build files in Gradle:
See, https://docs.appdynamics.com/javadocs/java-agent-api/v4.5/ for Javadoc reference for the agent API.
Common Use Cases
Starting and Ending a Synchronous Business Transaction
checkout()is called. The Business Transaction ends when the method does. Encapsulating the method body in a try/finally block ensures that you end the Business Transaction even if the method itself throws an exception or otherwise terminates without reaching the end.
Alternatively you can use try-with-resources pattern:
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.
Alternatively, try-with-resources pattern is supported:
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 async Business Transaction ends.
Defining an Exit Call
Given an inventoryServer.verifyQuantities(orders) which makes a request to another process, you can monitor that request as an Exit Call 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:
The above code modifications defines 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:
Defining an Asynchronous Thread Handoff
If your checkout method also does a thread handoff and executes some business logic you would be interested in monitoring in a separate thread, register the worker thread with the Business Transaction.
To instrument this, modify the add method to mark a thread handoff and then start a new segment where the thread begins running.
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 Executor mode.
Adding Data to Snapshot or Analytics
Often there are values of interest in the code that are helpful to add to snapshots to aid in 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 if it had been collected with a Method Invocation Data collector
To report a total checkout amount to Business Transaction analytics and have it present in APM snapshots, use the following code:
Defining a Custom Metric or Event
It can also be useful to report a value as a custom metric:
Reporting custom metrics and events is possible irrespective of the Business Transaction context.