Works with:

You can use data collectors to supplement business transaction and transaction analytics data with application data. The application data adds context to business transaction performance issues. For example, they may show the values of particular parameters or return values for business transactions affected by poor performance. 

This data shows the business context affected by performance issues, such as the specific user, order, or product.  

Types of Data Collectors

There are two types of data collectors:  

  • Method invocation data collectors - Capture code data, such as method arguments, variables, and return values.
  • HTTP data collectors - Capture the URLs, parameter values, headers, and cookies of HTTP messages exchanged in a business transaction. 

See Collect Transaction Analytics Data.

View Collected Data

When applied to business transactions, the data collectors supplement the information shown in transaction snapshots. The information captured by HTTP data collectors appears in the HTTP DATA and COOKIES sections, while method invocation data appears in the Business Data section. 

To view collected data:

  1. Navigate to the Transaction Snapshots pane. 
  2. Double-click the transaction for which you want to view data for.
  3. Click Data Collector to view collected data.

Configure a Data Collector

To configure data collectors, you need the Configure Diagnostic Data Collectors permission. Follow these steps to configure a data collector:

  1. Identify the method on which to capture data. To do this, define the method signature and (optionally) filters based on the value of a code point in the method (such as, return value or argument). 

  2. Specify the actual code point that serves as the source of the data. 

  3. If the data collector applies to business transactions, then select the applicable business transactions. 

When creating a data collector, you typically need to know the code on which you are setting up the collector, and whether it is based on access to the source code for the application, or its documentation. For the JVM 1.5 and .NET application environments, you must restart the JVM or application server if your method invocation data collector results in modifications to instrumentation configuration (class name, method name, method parameters, and so on). 

These platform-specific considerations apply to data collectors:

  • For C/C++ SDK: Create a method data collector using the appd_bt_add_user_data function(), not the Controller UI as described here. See C/C++ SDK Reference.

  • For Node.js Agent: Create a method data collector using only the addSnapshotData() Node.js API, not the Controller UI as described here. See Node.js Agent API Reference.
  • For Python Agent: Create a method data collector using the add_snapshot_data() Python Agent API, not the Controller UI. See Python Agent API Reference.

  • For PHP method data collectors, only the with a Class Name that option is valid. You cannot add a method data collector to a standalone PHP function.

Configure a Data Collector Automatically

You can add a data collector directly from a transaction snapshot through the call graph. This automatically adds the class and method for you.

  1. Double-click a call graph.
  2. Drill down to the node you want. 
  3. Right-click the method you want.
  4. Click Configure Instrumentation for this Class/Method.
  5. Complete the wizard.

Configure a Data Collector Manually

Data collectors can be manually configured in at least two ways. 

From the left pane:

  1. Click Configuration in the left pane.
  2. Click Instrumentation.
  3. Click the Data Collectors tab, and click Add below the data collector box for the type of data collector you want to add. The data collector configuration panel displays.

From a call graph:

  1. Double-click a call graph.
  2. Click Data Collectors in the menu bar. 
  3. Click Actions.
  4. Click Configure Data Collectors.
  5. Click Add at the bottom of the data collector box for the type of data collector you want to add. The data collector configuration panel displays.

Note the following platform-specific considerations applicable to data collectors:

  • C/C++ SDK - Create a method data collector using the appd_bt_add_user_data function(), not the Controller UI as described here. See C/C++ SDK Reference.
  • Node.js Agent - Create a method data collector only using the addSnapshotData() Node.js API, not the Controller UI as described here. See Node.js Agent API Reference.
  • Python Agent - Create a method data collector using the add_snapshot_data() Python Agent API, not the Controller UI. See Python Agent API Reference.

  • PHP method data collectors - Only the "with a Class Name that" option is valid. Also, you cannot add a method data collector to a standalone PHP function.

The general steps for configuring a data collector are: 

  1. Identify the method on which to capture data. To do this, define the method signature and (optionally) filters based on the value of a code point in the method (such as return value or argument). 
  2. Specify the actual code point that serves as the source of the data. 
  3. If the data collector applies to business transactions, choose the applicable business transactions. 

Typically, creating a data collector requires knowledge of the code on which you are setting up the collector, whether based on access to the source code for the application or its documentation. For some application environments, including JVM 1.5 and .NET, you will need to restart the JVM or application server if your method invocation data collector results in modifications to instrumentation configuration (class name, method name, method parameters, and so on). 

Configuration Notes

  • The Apply to new Business Transactions option applies the collector to business transactions created after you have configured the data collector. Otherwise, the data collector applies only to the business transactions you select in the subsequent data collector configuration pane. 
  • For Class, select the match condition that the data collector can use to identify the class, such as class name, implemented interface name, and so on. If matching by class name, then use the fully qualified name of the class, as appropriate for the application platform. For example, the form of the equals field value would be: 
    • In Java: com.appdynamics.model.Item
    • In .NET: Bookstore.Item
    • In PHP: book

  • Is this Method Overloaded: If this is an overloaded method, then add parameters that identify the signature. You must create a data collector definition for each form of the method for which you want to capture data. For example, given the overloaded method in this table, to capture data for only the second two forms, you would need to create two data collectors. The parameters to configure are shown:

    Signature

    Parameters to Configure

    getName()
    • None
    getName(int studentId)
    getName(int studentId, string name)

  • You can refine the method selection to meet specific conditions. If you configure more than one match condition, then all match conditions must be satisfied by the request for the data collector to be applied to the request.  

  • Once you identify the method, specify the code point from which you want to capture data, such as the method return value, argument, or a value captured by the getter chain on the invoked object. Configure this code point in the Specify the Data to Collect from this Method Invocation section of the configuration settings.

  • HTTP data collector can capture data from HTTP parameters, request attributes, cookies, and other data. Notice that the Content-Length HTTP header is already captured in AppDynamics as the Average Request Size metric. However, you may choose to configure a data collector for this header to have the value appear in transaction snapshots, providing you insight into, for example, whether message size corresponds to slow performance. 

  • You can configure multiple data collectors. The effect of multiple data collectors is cumulative. For example, if you add a custom data collector that does not include the collection of the URL HTTP request attribute, but keep the Default HTTP Request Data Collector configuration in which the URL is configured to be collected, then the URL is collected.

Method Invocation Data Collector Example

Method invocation data collectors are applicable to Java and .NET.

In this example of a manual setup (not using the wizard), we'll set up a method invocation data collector on a Java application. We want to create a data collector on the method getCartTotal(), which is shown in this code snippet with the method getUser() and which we will use later as a data source.   

package com.appdynamicspilot.model;
...
public class Cart implements java.io.Serializable {
    ...
    private Double fakeAmount = 0.0;
    ...
    private User user; 
    ...
    public User getUser() {
        return user;
    }
    ...
    public Double getCartTotal() {
        if (fakeAmount == 0.0) {
            double total = 0;
            if (items != null) {
                for (Item item : items) {
                    total += item.getPrice();
                }
            }
            return total;
        } return fakeAmount;
    }
   ...
}

To configure a data collector for an application, add a data collector and then configure it:  

  1. When you add your data collector, make your selections as appropriate for your configuration.
  2. Add a class and a method, if not already filled in. Class and Method Name are used to identify the method. 
  3. At the Enable Data Collector for checkboxes, select Transactions Snapshots to add metadata for troubleshooting purposes and for APM snapshots, or select Transaction Analytics to collect metadata about every execution of the transaction to use later in the analytics platform. It is recommended that you start with ONLY Transactions Snapshots. Enable Transactions Analytics after the targeted data collection is confirmed.
  4. Click Add Parameter or Add Match Condition to select the correct parameter from the popup. 
    1. Method Parameters are added if the method is overloaded. Clicking Add Parameter adds the Param Index 0. Add the fully qualified class name for the parameter. 
    2. Match Conditions allow you to pick specific data when a method or line of code is called multiple times. Match Conditions engage method parameters or return values. Selecting Add Match Condition opens the Create Match Condition popup. Make your selections, and then click Save.  
    3. When setting up your data collector, note the checkbox beside Apply to new Business Transactions. 
      1. Checking this box automatically applies the rule to new business transactions.
      2. Not checking this box requires you to manually apply the rule to business transactions by navigating to Configuration > Instrumentation > Data Collectors.
    4. To add multiple collection types, click Add beneath Specify the Data to Collect from this Method Invocation to configure the source of data. For this section of code, use an invoked object and a getter chain of user.getCustomerName. This code snippet is an example of how to capture the user name on the invoked object. The Cart class instantiates a User object based on the following class in the same package as Cart. Note that the User class includes a method for returning the name of the user, getCustomerName().

    package com.appdynamicspilot.model;
    ...
    public class User implements java.io.Serializable {
        ...
        private String customerName = null;
        ...
      
        public String getCustomerName() {
            return customerName;
        }
        public void setCustomerName(String customerName) {
            this.customerName = customerName;
        }
        ...
    } 

    Using a getter chain, you can identify this method as another data source in the same data collector. For example, you could select Invoked Object as the source of the data. The getter chain getUser().getCustomerName() is the operation on the invoked object. 
    For the PHP agent, if a method return value collected by MIDC is not stored in any variable, it is seen as null in both snapshot and Analytics data.

  5. When finished, click Save.

After you configure the method invocation data collectors, you can click Configure Transactions using this Data Collector on the Instrumentation pane to drag and drop (or highlight and move) the transactions to a given data collector.

When complete, transaction snapshots for slow, very slow, and stalled transactions, the transaction snapshots will include the specified user data. 

HTTP Data Collector Example

In the HTTP Data Collector configuration, specify the request data that you want to display in the snapshot.

To configure a data collector, add a data collector and then configure it:  

  1. Make your selections as appropriate for your configuration.
  2. Determine if you are collecting parameters, cookies, session keys, or header data.
  3. Click +Add beneath a data type to specify the request data that you want to display in the snapshot, and fill in as appropriate.
    When setting up your data collector, note the checkbox beside Apply to new Business Transactions. 
    1. Checking this box will automatically apply the rule to new business transactions.
    2. Not checking this box requires you to manually apply the rule to business transactions by navigating to Configuration > Instrumentation > Data Collectors.
  4. When finished, click Save.