Data collectors allow you to supplement your performance monitoring or transaction analytics data with application data. Application data can reveal the business context in which performance issues or errors occur, for example, by capturing the name of the user making a request, an order amount, or the product ordered.
Types of Data Collectors
The types of application data you can capture comes in two forms:
- 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.
For information on how transaction analytics uses data collectors, see Configuring Transaction Analytics.
View Data Collector Results in Transaction Snapshots
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 USER DATA section:
When you configure data collectors, the snapshots show the application data for slow and very slow transactions. App agents do not collect data for stalled transactions.
How Do Data Collectors and Information Points Differ?
Data collectors and information points have a lot in common. As you would for a data collector, to configure an information point you specify a point in code from which to capture application data.
However, the ways that information points and data collectors are used are very different:
- Data collectors capture the application data value for a given transaction, and shows that value in the transaction snapshot for that transaction instance. Data collectors are meant to give you the application context for a transaction, which can help you with troubleshooting and understanding transaction performance issues.
- Information points, on the other hand, capture the value of a point across transactions and let you apply some computation to the collected values, such as adding them together or averaging them.
Information points are useful, for example if you have a method for completing a transaction that may be used across business transactions. By setting an information point on the method variable, you can get the sum of a value in the method (such as the sales total, for example), for all invocations.
Alternatively, you can get performance data for a particular point in code (number of invocations, for example) across transactions. Another way to think of an information point is as an application-wide metric, although it does not appear in the metric browser. Information points appear in the Information Points page.
Configuring a Data Collector
You add a data collector from the Configuration > Instrumentation page. Click the Data Collector tab and click the Add button below the Method Invocation Data Collectors panel or the HTTP Request Data Collectors panel.
The new data collector configuration window appears as follows:
Note the following platform-specific considerations applicable to data collectors:
- For the C/C++ agent, you can create a method data collector using the
appd_bt_add_user_data function(), not the Controller UI as described here. See
- For the Node.js agent, you can 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.
- For the Python agent, you can 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. Also, you cannot add a method data collector to a standalone PHP function.
The general steps in configuring a data collector are:
- Identifying the method on which to capture data. To do this, you define the method signature and optionally, filters based on the value of a code point in the method (such as return value or argument).
- Specifying the actual code point that serves as the source of the data.
- 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).
- The Apply to new Business Transactions option applies the collector to business transactions created after you have configured this collector. Otherwise, the data collector only applies to the business transactions you select in the subsequent data collector configuration screen.
- You can configure multiple data collectors. The effect of multiple data collectors is cumulative; if you add a custom data collector that does not include collection of the URL HTTP request attribute, for example, but keep the Default HTTP Request Data Collector configuration in which the URL is configured to be collected, the URL will be collected.
To prevent collection of the URL, Session ID, User Principle, or other fields, make sure that no data collectors are configured to collect these data points.
- For Class, select the match condition that the data collector can use to identify the class. The collector can match by the value of the class name, implemented interface name, annotation name, or more. (Note that "with a Class Name that" is the only match condition applicable for PHP. Also PHP method data collectors cannot be added to a standalone PHP function.) If matching by class name, 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:
- In .NET:
- In PHP:
- In Java:
Is this Method Overloaded: If this is an overloaded method, add parameters that identify the signature. You will need to 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 the following table, to capture data only for the second two forms, you would need to create two data collectors. The parameters to configure would be as shown:
|Signature||Parameters to configure|
You can further refine the method selection so that data is collected only on methods that satisfy a match condition. The match condition can test a parameter value of the method, the method's return value, or a value returned by a method getter chain you specify. If you configure more than one match condition, all match conditions must be satisfied by the request for the data collector to be applied to the request. For an example of a getter chain-based match condition, see Data Collector Configuration Examples.
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 getter chain on the invoked object. You 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, session keys and headers. Note that the Content-Length HTTP header is already captured in AppDynamics as the Average Request Size metric, available in the metric browser. However, you may choose to configure a data collector for this header to have the value appear in transaction snapshots, giving you insight, for example, on whether message size corresponds to slow performance.