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:

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.

How to Configure Custom Correlation

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.

TIP

The XML file named custom-activity-correlation.xml needs to be placed in the AGENT_HOME location parallel to the AppDynamics app-agent-config.xml agent configuration file.

The string "singularityheader" (all lowercase) is the default key we use in map or property structures we tag. It can be changed in the custom XML if necessary by using the <header-key> element in <payload-operation>.

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.