Updated 6/20/18
The following article is intended for users who wish to implement custom correlation between Java applications/tiers using the AppDynamics' Java App Agent version 3.8 and higher.
For information regarding the .NET Agent, see here: Custom Correlation for .NET Applications
Contents:
What is Custom Correlation?
Custom correlation enables you to configure AppDynamics to correlate transactions across tiers, or across parent-child threads in complex multithreaded applications when the default detection mechanisms are not capable of auto-correlating. To correlate a distributed invocation, the AppDynamics agent must propagate a unique correlation key by using the extension points of the distributed protocol or by decorating the payload.
The AppDynamics agent needs to know what methods to measure. Therefore, when defining a custom correlation you have to consider:
- How to propagate the correlation key.
- What exactly you want to measure.
When is Custom Correlation Needed?
When you are monitoring applications that use unsupported frameworks and protocols, custom correlation may be the answer. Use custom correlation XML configuration to achieve business transaction correlation across tiers when the following conditions exist:
- Producer
- There is an easily-defined method call to configure as an exit point on the producer.
- There is a method call where one of the parameters or a return value exposes the payload object, and that method call occurs during execution of the exit point on the producer.
- Consumer
- There is an easily-defined method call to configure as a POJO entry point on the consumer.
- There is a method call where one of the parameters or a return value exposes the payload object.
Use Cases
For custom correlation on communication protocols between nodes such as HTTP and JMS:
- We add transaction contextual information for remote calls. For example, AppDynamics can add transaction context onto HTTP headers and JMS message properties.
For custom correlation within a node:
- For example, for ESB job objects and ExecutorService thread workers, we can save the transaction context against thread hand-offs so they can be picked up when async segments start.
Implementation
To implement custom correlation, you use XML configuration to specify how to instrument the application. The primary factors governing the exact configuration are the data structures and the sequence of code execution. You can use, custom-activity-correlation.xml, the XML configuration template shipped with the APM Java Agent (found in the conf directory when you unzip your Java agent download zip file) or one of the sample XML files (described in topics linked at the bottom of this page) as a starting point.
The general steps to configure custom correlation are the following:
- Identify producer and consumer methods.
- Configure a custom exit point on the producer and POJO entry point on the consumer.
- Configure the producer to add the correlation metadata to the exit point.
- (Optional) Configure and identify validation methods on the producer.
- Configure the consumer to read the entry point.
- (Optional) Configure and identify validation methods on the consumer.
Unsupported Scenarios
In general, cross-process, ID-based correlation is not supported.
Consider a scenario involving consecutive processes with a shared ID such as the following: three separate, consecutive processes are all considered to be segments of the same business transaction. The processes are sequential, but the processes can also theoretically overlap to some degree.
- Process 1 starts and establishes an ID.
- That ID is written to a file or database, Process 1 continues and eventually exits.
- Process 2 starts after Process 1 exits. Process 2 looks up the ID and some stored data related to the ID, continues and eventually exits.
- Same for Process 3
Sun RMI Support
We do not correlate at the protocol level for Sun RMI because standard, out-of-the-box Sun RMI does not have a place to inject the transaction context in the method invocation.
Examples:
Published on 6/5/2015
Updated for 4.4 on 6/20/2018
