This topic introduces the Java Agent API and instrumentation SDK (iSDK), and also describes the common use cases for the API.
About the Java Agent API and iSDK
AppDynamics automatically detects an application activity out-of-the-box. The agent ships with an out-of-the-box configuration that -for supported application frameworks - applies instrumentation to the application that identifies the following:
- Where the Business Transaction activity starts
- Where thread handoffs happen
- Where calls to downstream systems are made and how to inject correlation headers into outbound messages and retrieve them from inbound messages. This ensures 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 Agent APIs that allow the application developer to make code changes to add calls to the agent. This helps to allow the agent to identify and follow Business Transactions as they execute, providing end-to-end visibility for any application.
For scenarios where it is not possible to change the application code, for example, to add instrumentation to a third party product or framework, an 'instrumentation SDK' is provided that supports the use of these APIs. The iSDK allows developers to build 'interceptors', which the agent injects into application bytecode at specified points on startup. These interceptors can contain any java code (including calls to the Agent API), which is executed when the code provided in the interceptor is run before or after the intercepted method itself executes.
Use of any of the Agent APIs 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 programmatically:
- 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 prioritizes the success of the application transactions over instrumentation. Therefore, if any of the Agent API calls fail, they do not throw exceptions disrupting the transaction flow, but 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.
See, https://sdkdocs.appdynamics.com/javadocs/java-agent-api/v4.5/ for the Javadoc reference for the agent API. User guides for the Agent API and the instrumentation SDK are also provided to illustrate the usage and common use cases.
Installing the Dependency
The Agent API jar can be accessed directly or downloaded from Maven Central or 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 one of the following: