Showing results for 
Show  only  | Search instead for 
Did you mean: 
AppDynamics Team (Retired)

This topic describes how transaction correlation works in the Java environment. In principle, it works largely the same for .NET and the other language agents.


Transaction correlation enables AppDynamics to do distributed transaction tracing in modern web applications. Transaction correlation provides the ability to draw the application flow map and depict the flow of business transactions across multiple tiers and to external services.


Transaction correlation maintains the business transaction context across all tiers and threads as the requests are processed. Whatever the transaction does across all these tiers is counted as an activity for that business transaction.


Table of Contents


Transaction Correlation terminology

Business Transaction (BT) is fundamentally distributedBusiness Transaction (BT) is fundamentally distributed


Originating tier/segment

Tier 1 in the diagram is where the first significant entry point is discovered, named, and instrumented. This is called the originating tier.


Continuing tier/segment
(or downstream tier)
Every other thread spawned either in the same JVM or externally is considered a continuing segment or continuing tier

In the diagram, tiers 2, 3, and 4, and the JMS /Messaging Bus are continuing/downstream segments. Metrics are reported to the Controller for each segment.



AppD Maintains the Transaction Context

For Remote Calls

AppDynamics agents decorate the protocol headers to add transaction contextual information.


For Async threads
(intra-JVM and intra-CLR)

AppDynamics agents save transaction context against thread hand-offs to be picked up when the async segment starts.



When done the right way, this does not change application behavior. AppDynamics agents only add where there is extensibility, such as found in HTTP headers and JMS properties. Every "transaction segment" reports its own metrics. 


Typical Cross-JVM Calls and Correlation Medium

This diagram shows how the context is maintained across tiers for various mediums.

Typical cross-JVM callsTypical cross-JVM calls


Correlation for HTTP

We add a header for HTTP calls because, by definition, the headers are extensible. The name of AppDynamics' header for propagating correlation information is "singularityheader".


Adding custom headers to carry transaction information is safe when:

  • you don't use any well-understood header names like "Accept-Language"
  • the contents of the header value is "HTTP-safe"

This diagram illustrates the generic structure of an HTTP request. When a client tier makes an HTTP call, the AppDynamics byte code interceptor adds a safe header that uniquely identifies this transaction. The AppDynamics byte code interceptor on the receiving Servlet (for example), reads the header and carries forward the transaction context. The Controller reconstructs the flow based on the information received from each node in the flow.

HTTP RequestHTTP Request


Correlation for JMS

We add a message property for JMS calls because by definition, the message properties are extensible. Adding custom message properties to carry transaction information is safe when:

  • you don't overwrite any existing properties
  • you choose a unique property name
  • the value of the property is valid content

This diagram illustrates the generic structure of a JMS call.

JMS callJMS call


Correlation Header 

The following diagram shows the contents of the AppDynamics correlation header.

Correlation header contentsCorrelation header contents





















Custom Correlation

If the underlying framework/API is not supported by out-of-the-box correlation by AppDynamics, then there is a provision to come up with the custom configurations by analyzing the flow of the transaction.


For more details, refer to:


Cross Application and Federated Cross Application Flow

Cross application flows show the performance impact between business applications within a Controller account. For environments that require a larger picture of business performance, federated cross application flows allow AppDynamics to correlate business transactions across business applications in different accounts that may be on different Controllers. For details, refer to:


Published on <u+200e>05-06-2015.

Content revised 7/30/18



With the new SAP agent it uses the HTTP listner to collect data from SAP but when I set it up is complains about the HTTP header


2018-07-13 10:59:57.570435| 2|httpclient| Not using an HTTP proxy
2018-07-13 10:59:57.570562| 2|env| Starting AppDynamics Agent libagent v4.4.4 v4.4.1.0 SHA (id: )
2018-07-13 10:59:57.570599| 2|env| Instrumenting process 20533 with working directory /opt/appdynamics/appdhttpsdk
2018-07-13 10:59:57.570609| 2|env| Running on OS: Linux (version #1 SMP Mon Feb 20 02:26:38 EST 2017), CPU architecture x86_64
2018-07-13 10:59:57.570621| 2|env| Controller: Telkom@, ssl: 0
2018-07-13 10:59:57.570632| 2|env| Analytics processor: localhost:9090
2018-07-13 10:59:57.570852| 2|agent| Agent state reset
2018-07-13 10:59:57.570896| 2|env| Application name: SAP_BW
2018-07-13 10:59:57.570929| 2|env| Tier name: BW
2018-07-13 10:59:57.570939| 2|env| Node name: SAP_BW_bisit_BW5_02
2018-07-13 10:59:57.612085| 2|agent| Scheduling new config update request
2018-07-13 10:59:57.705277| 3|httpclient| Invalid header in Http response
2018-07-13 10:59:57.705351| 3|agent| Agent configuration update error {http status 401}


How can one fix this?


What is the name of the HTTP header used to convey the correlation information?

AppDynamics Team

Appdynamics header name to propagate the correlation information is "singularityheader".

AppDynamics Team (Retired)

@Walt.Kacynski  and @Richa.Panwar : Thank you for surfacing this useful distinction. I've edited the article to include the AppDynamics HTTP header name.

Version history
Last update:
‎04-13-2021 11:25 PM
Updated by:
June 26 Webinar
Discover new Splunk integrations and AI innovations for Cisco AppDynamics.

Register Now!

Observe and Explore
Dive into our Community Blog for the Latest Insights and Updates!

Read the blog here