Configure Custom Correlation for .NET Applications

[Erin]

Updated 9/28/18

The following article is intended for users who wish to implement custom correlation between .NET applications/tiers using the AppDynamics' .NET App Agent version 3.8 and higher.

You can also implement custom correlation using the AppDynamics' .NET Core Microservices Agent version 4.5.2 and higher by following slightly different steps.

For information regarding the Java Agent, see here: Custom Correlation for Java Applications

Contents:

• What is Custom Correlation?

• When is Custom Correlation Needed?

• Use Cases
• Implementation
  • Steps to Configure Custom Correlation
  • Identify the Producer and Consumer Methods to Instrument
  • Configure the Producer
  • Configure the Consumer
  • Configure Custom Correlation for the .NET Microservices Agent
  • Restart the coordinator and the instrumented applications

What is Custom Correlation? 

Custom correlation enables the user 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. 

Correlation establishes the relationship between exit points on upstream tiers to entry points on downstream tiers. For transaction correlation to work, you must install the .NET Agent on both tiers.

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. When defining a custom correlation consider:

1. How to propagate the correlation key.
2. What exactly you want to measure.

 

When is Custom Correlation Needed? 

Use custom correlation when monitoring applications that use unsupported frameworks and protocols.

Use custom correlation XML configuration for 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 POCO entry point on the consumer.
  • There is a method call where one of the parameters or a return value exposes the payload object.

In custom correlation, the producer refers to the originating tier that makes the exit call. The consumer refers to the downstream tier that is the destination for the producer's exit call. If the .NET Agent automatically discovers the exit point for the transaction on the producer, you don't have to manually configure a producer. If it discovers the entry point on the consumer, you don't have to manually configure a consumer. 

Use Cases 

For custom correlation on communication protocols between nodes such as HTTP and JMS:

• 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 ESB job objects and ExecutorService thread workers, save the transaction context against thread hand-offs so they can be picked up when async segments start.

 

Implementation

To implement custom correlation, 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. Use the attached sample XML configuration as a starting point.

NOTE: For AppDynamics version 3.8, the correlation element does not inherit instrumentation element configuration from parent producer or consumer elements. Configure a different method in the correlation Instrumentation element for correlation to work. In most cases, the producer and consumer reside on separate machines, so they would have separate configuration files. The attached sample file demonstrates two standalone applications on the same machine: Producer.exe and Consumer.exe.

Steps to Configure Custom Correlation:

Before you begin: Install and configure the .NET Agent on both the producer and the consumer. If the producer is a Windows service or standalone application that does not implement any of the frameworks we instrument by default, configure a POCO entry point for a class/method in your service for the agent to begin instrumentation.

1. Identify producer and/or consumer methods to instrument.
2. Configure a custom exit point on the producer and/or POCO entry point on the consumer.
3. Configure the producer to add the correlation metadata to the exit point.
4. (Optional) Configure and identify validation methods on the producer.
5. Configure the consumer to read the entry point.
6. (Optional) Configure and identify validation methods on the consumer.
7. Restart the coordinator and instrumented applications.

To identify producer and consumer methods to instrument:

Before you configure custom correlation, you must identify the methods to instrument on both the producer and the consumer.

On the producer identify the following:

1. An exit point method that calls to the consumer.
2. A payload method that executes within the exit call method execution and whose parameters or return value expose the payload object.

On the consumer:

1. A POCO entry point method that handles the producer's exit call.
2. A payload method whose parameters or return value expose the payload object.

Currently, for the .NET Agent, the instrumentation method (exit or entry point) and the payload methods must be different methods.

To configure the producer:

Configure the agent properties in the config.xml file in the agent config directory. See .NET Agent Directory Structure. All custom correlation configurations go inside the activities element, a child of the App Agents element. See .NET Agent Configuration Properties.

1. Configure the exit point for the producer in the producer Instrumentation element.
2. Configure the payload method in the correlation Instrumentation element.

The following is a sample activities element with a producer element:

<activities>
    <producer>
        <!-- Configure the exit point. -->
        <instrumentation>
            <class-name>Producer.IdentifyTransaction</class-name>
            <method-name>Test</method-name>
            <match-type>MATCHES_CLASS</match-type>
            <param-types>Producer.IdentifyTransaction</param-types>
        </instrumentation>
        <identifiers>
            <identifier name="IdentifyTransactionTest">              
                <data-gatherer-type>INVOKED</data-gatherer-type>
                <getter-chain>this</getter-chain>
                <user-defined-name>IdentifyTransactionTest</user-defined-name>
                <transformer-type>USER_DEFINED_NAME</transformer-type>
            </identifier>
        </identifiers>
        <correlation>
            <!-- Configure the payload method. -->
            <instrumentation>
                <class-name>Producer.IdentifyTransaction</class-name>
                <method-name>TestCorrelation</method-name>
                <match-type>MATCHES_CLASS</match-type>
                <param-types>Producer.IdentifyTransaction</param-types>
            </instrumentation> 
            <payload-pointer>
                <data-gatherer-type>POSITION</data-gatherer-type>
                <position>0</position>
                <getter-chain>this</getter-chain>
                <transformer-type>GETTER_METHODS</transformer-type>
            </payload-pointer>
            <payload-operation>
                <access-type>method</access-type>
                <access-method>setCorrelationKey</access-method>
                <param-types>String</param-types>
            </payload-operation>
        </correlation>
    </producer>

     
</activities>

To configure the consumer:

Configure the agent properties in the config.xml file in the agent config directory. See .NET Agent Directory Structure. All custom correlation configurations go inside the activites element, a child of the App Agents element. See .NET Agent Configuration Properties.

1. Configure the entry point for the producer in the consumer Instrumentation element.
2. Configure the payload method in the correlation Instrumentation element.

The following is a sample activities element with a consumer element:

<activities>
        <consumer identify-transaction="true">
            <!-- Configure the entry point. -->
            <instrumentation>
                <class-name>Consumer.IdentifyTransaction</class-name>
                <method-name>Test</method-name>
                <match-type>MATCHES_CLASS</match-type>
            </instrumentation>
            <correlation>
                <!-- Configure the payload method. -->
                <instrumentation>
                    <class-name>Consumer.IdentifyTransaction</class-name>
                    <method-name>TestCorrelation</method-name>
                    <match-type>MATCHES_CLASS</match-type>
                </instrumentation>
                <payload-pointer>
                    <data-gatherer-type>POSITION</data-gatherer-type>
                    <position>0</position>
                    <getter-chain>this</getter-chain>
                    <transformer-type>GETTER_METHODS</transformer-type>
                </payload-pointer>
                <payload-operation>
                    <access-type>method</access-type>
                    <access-method>getCorrelationKey</access-method>
                </payload-operation>
            </correlation>
        </consumer>
    </activities>

 

Configure Custom Correlation for the .NET Microservices Agent:

You can implement custom correlation configuration for the .NET Core Microservices Agent in much of the same way as instructed above. The difference is that the location of the XML configuration goes into the AppDynamicsConfig.json file and not the config.xml file.

1. Configure the file that contains the custom correlation XML in the AppDynamicsConfig.json file.
   NOTE: The supplied file name can contain an absolute or relative path. If the path is relative (or only a file name is supplied), the location is resolved relative to the AppDynamicsConfig.json file.
   
   

   {
       "controller": {
           ...
       },
       "application": {
            ...
       },
       "instrumentors": {
           "customCorrelationConfig": "custom-correlation.xml",
           "enable": [ ... ],
           "disable": [ ... ]
       },
       ....
    }

   See AppDynamicsConfig.json File for a sample .json file.
   
   

2. Populate the custom correlation configuration file:

   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <activities>
        <consumer identify-transaction="true">
            <instrumentation>
                <class-name>Application.Program</class-name>
                <method-name>Method</method-name>
                <match-type>MATCHES_CLASS</match-type>
            </instrumentation>
            <correlation>
                ....
            </correlation>
        </consumer>
    </activities>

   The XML inside the <activities> element has the exact same schema as the existing custom correlation XML found under the <activities> element in config.xml (MSI agent).

Restart the coordinator and the instrumented applications:

After you complete the configuration on the producer and consumer, you must restart the AppDynamics.Agent.Coordinator service and instrumented applications.

Published on 6/5/2015.

Updated for 4.5.2 on 9/28/2018.