What is the Business Transaction discovery life cycle?

[pclark]

To troubleshoot business transaction discovery it is helpful to have an understanding of the AppDynamics entity life cycle. A business transaction is a discrete piece of business application functionality that is tracked from beginning to end, potentially across multiple tiers of processing, to measure the time it takes to complete the functionality.

Phase 1: Business Transaction Discovery

The discovery of a business transaction (BT) is accomplished by detecting where the business transaction begins and instrumenting its entry point. An entry point is the specific class and method (Java and .NET), operation or URI that kicks off the discrete bit of functionality that we want to measure. The exact entry points that are instrumented are agent dependent.  For details on dynamic language agents, see the supported environments pages for each agent in the product documentation: Supported Environments and Versions.

Where does a BT begin?

• Where the core business logic is processed and executed.
• It might not necessarily be the first application component in the path of the request.
• A Java Servlet that handles a complex HTTP request is a good example of an entry point.
• In some cases the Servlet might merely forward the request to another component such as an EJB Bean that has the core business logic. In this case the EJB Bean is the right place to define the transaction as it is easier to differentiate one transaction from another based on the EJB Bean executing it.
• For PHP the entry point is typically a URI or a page callback name, MVC controller action, page template name, or page template.
• For Node.js the entry point is typically a method, operation or a URI. 

Was BT Discovery Successful?

Use the following steps:

1. If you see BTs, but some that you expect to see are missing, first check that the BT limit was not exceeded. Was the BT limit reached? See All Other Traffic Business Transaction.
2. If the BT limit was not reached or you do not find evidence of the business transaction in the traffic details of the overflow BT, go to the next step.
3. Are you using a web framework? Yes, go to Confirming BT Instrumentation for Web Frameworks
4. Are you running a background task? Yes, go to Confirming BT Instrumentation for Batch Frameworks
5. If your entry point was not instrumented (see steps 3 and 4) and find entry points did not reveal a useful entry point, consider contacting AppDynamids Support at: http://www.appdynamics.com/support/.
6. If you find evidence in the BCT log that the entry point was instrumented, check for entry point exceptions.

       a. Look in the agent logs for entry point exceptions. For details on retrieving the logs, see Request Agent Log Files.

       b. If you find exceptions for your entry point, contact support for additional assistance.

       c. If you do not find any exceptions, move on to phase 2, registration.

Phase 2: BT Registration

When an entry point is successfully instrumented, it is assigned a name based on the rules for the entry point type or the custom naming rule (if applicable). Every BT is stored in the BT table in the controller database. The agent detects when the entry point is invoked and sends a BT registration request to the controller.

Registration is when each BT is assigned an ID by the controller. After the ID is assigned, communication between the agent and controller uses the ID to identify exactly which BTs are being reported and stored in the controller database. You can review the BT registration log entries in the REST log.

Use the following steps to confirm BT registration:

1. Generate and retrieve the REST log. For details on how to do this, see Request Agent Log Files. Look for registration and response details.

In the following ViewCart BT request, you can see the entry point type is STRUTS_ACTION, the internal name is ViewCart.sendItems. At this point the id=0 and name=null.

[AD Thread Pool-Global1|AD Thread Pool-Global1] 20 Nov 2012 09:49:44,491 DEBUG BusinessTransactionRegistry -
REST - Sending Binary request - URL \[ /controller/instance/2/btregistration\]
Payload \-****\**\**BT Registration Data*\******\*
...
<AConfigObject ( AConfigObject ( com.singularity.ee.controller.api.dto.transactionmonitor.transactiondefinition.BusinessTransaction@8f000904 id = 0 name = null ) applicationId = 0 ) [ id=0, entryPointType=STRUTS_ACTION, internalName=ViewCart.sendItems, componentId=2, applicationComponentName=null, matchCriteria=com.singularity.ee.controller.api.dto.transactionmonitor.transactiondefinition.MatchCriteria@74cb7e2c, createdOn=null, background=false, configuration=null, createdNodeId=0, enabledForEUM=false, eumAutoEnablePossible=null]>

In the following response you can see that the Controller assigned an id=80 and the name=ViewCart.sendItems.

[AD Thread Pool-Global1] 20 Nov 2012 09:49:44,723 DEBUG BusinessTransactionRegistry -
REST - Reading Binary payload - URL [ null]
Size : [5376]
Payload -********BT Registration Data********
...
<AConfigObject ( AConfigObject ( com.singularity.ee.controller.api.dto.transactionmonitor.transactiondefinition.BusinessTransaction@8f000904 id = 80 name = ViewCart.sendItems ) applicationId = 4 ) [ id=80, entryPointType=STRUTS_ACTION, internalName=ViewCart.sendItems, componentId=2, applicationComponentName=null, matchCriteria=com.singularity.ee.controller.api.dto.transactionmonitor.transactiondefinition.MatchCriteria@2ea28708, createdOn=null, background=false, configuration=null, createdNodeId=3, enabledForEUM=false, eumAutoEnablePossible=null]>

2. If you do not see a successful registration request and response, look in the Controller Logs for related exceptions.

Phase 3 - BT metrics registration

After successful BT registration, the agent keeps a BT map in memory with the ID, type, and name for each BT. The next time the entry point is hit, the agent is ready to report metrics. A similar process of request and response between the agent and controller occurs and the controller assigns each metric an ID.

Use the following steps to confirm BT metric registration:

1. Generate and retrieve the REST log. For details on how to do this, see Request Agent Log Files.

2. Look for log entries showing metric registration.
   In the following request, you can see "BT:80", which we know from our review at phase 2 identifies the ViewCart.sendItems business transaction. The two metrics shown below represent Calls per Minute and Average Response Time for the ViewCart.sendItems BT.

[AD Thread-Metric Reporter0] 20 Nov 2012 09:50:44,079 DEBUG MetricSender - Sending REST request - URL [ /controller/instance/2/metricregistration]
 
 XML payload -<request>
...
<metric time-rollup-type="AVERAGE" name="BTM|BTs|BT:80|Component:2|Calls per Minute" hole-fill-type="RATE_COUNTER" cluster-rollup-type="COLLECTIVE"/>
<metric time-rollup-type="AVERAGE" name="BTM|BTs|BT:80|Component:2|Average Response Time (ms)" hole-fill-type="REGULAR_COUNTER" cluster-rollup-type="INDIVIDUAL"/>

In the following response you can see BT:80, identifying the ViewCart.sendItems BT. You can see that metric id=1815 was assigned to the Calls per Minute metric. A metric id=1813 was assigned to the Average Response Time metric.

[AD Thread-Metric Reporter0] 20 Nov 2012 09:50:44,346 DEBUG MetricSender - REST Response Received ->
 
<request>
...
<metric id="1815" name="BTM|BTs|BT:80|Component:2|Calls per Minute"/>
<metric id="1813" name="BTM|BTs|BT:80|Component:2|Average Response Time (ms)"/>

3.  If you do not see successful request and response for the metric, look in the Controller Logs for exceptions related to backend metric registration.

Phase 4 - BT metrics reporting

After successful, metric registration, BT metrics are reported to the controller every minute. Using the metric id, you can search the REST log for the metric upload.

Use the following steps to confirm BT metric upload:

1. Generate and retrieve the REST log. For details on how to do this, see Request Agent Log Files.

2. Look for log entries showing metric reporting uploads similar to the following:

[AD Thread-Metric Reporter0] 20 Nov 2012 09:50:44,361 DEBUG MetricSender -
REST - Sending Binary request - URL [ /controller/instance/2/metrics]
 Payload -********Metric Data********
...
<metric id='1815', value[sum=32, count=1, min=32, max=32, current=32]>
<metric id='1813', value[sum=8693, count=32, min=4, max=1614, current=53]>

3. If you do not see successful metric data uploads, look in the Controller Logs for related  exceptions.

Phase 5 - BT metrics roll up

App agents do not communicate with each other, they report metrics to the controller database. The controller aggregates the metrics from all nodes in each tier to present a unified overall picture in the Controller console.

If you have verified that phases 1-4 of the BT discovery life cycle have been successful and you are not seeing the expected BT metrics, contact AppDynamics Support for assistance: http://www.appdynamics.com/support/.