This page describes the Java Agent API, instrumentation SDK (iSDK), and the common use cases for the API.

Java Agent API and iSDK

Splunk AppDynamics automatically detects an application activity out-of-the-box. For supported application frameworks, the agent ships with an out-of-the-box configuration that applies instrumentation to the application that identifies the following:

  • Where the Business Transaction activity starts
  • Where thread handoffs occur
  • Where calls to downstream systems are made, and how to inject correlation headers into outbound messages and retrieve them from inbound messages. This ensures that Splunk 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 enables 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 enables 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. 

You can seamlessly combine any Agent APIs 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 indicates that there is no hard dependency between the application and the presence of the Java Agent within the JVM.

See https://sdkdocs.appdynamics.com/java-agent-api/v20.6/ 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.

Install the Dependency

You can access the Agent API jar directly, or download it from Maven Central or from the Splunk AppDynamics portal. The library version changes with each new API release, and is not tightly coupled to the version of the underlying agent.

To use Maven Central, add the dependency to your build files in one of the following:

  • Gradle:
dependencies {
    compile group: 'com.appdynamics.agent', name: 'agent-api', version: '20.6.0.30246'
}
CODE

or

  • Maven:
<dependency>
     <groupId>com.appdynamics.agent</groupId>
     <artifactId>agent-api</artifactId>
     <version>20.6.0.30246</version>
</dependency>
CODE