Using Application Trace Kit

Application Trace Kit (ATK) provides visibility into Java-based applications in which one or more ldt Java Agents have been embedded.
dts105
Application Trace Kit (ATK) provides visibility into Java-based applications in which one or more 
DevTest
Java Agents have been embedded.
Application Trace Kit also lets you manage the main components of the 
DevTest
Java Agent: the agent itself, the broker, and the consoles.
Application Trace Kit is a preview feature in this release.
2
2
Start the Application Trace Kit
Before you start the Application Trace Kit, ensure that the broker is running.
You can start the Application Trace Kit from the command line. The
bin
directory of a
DevTest
 installation contains the executable file. Add the
-u
option to specify the broker. For example:
C:\Program Files\CA\DevTest\bin>ATK.exe -u tcp://localhost:2009
You can add the
-console
 option to display console output.
C:\Program Files\CA\DevTest\bin>ATK.exe -u tcp://localhost:2009 -console
If you are running the Application Trace Kit on Windows and the Start menu includes an entry for
DevTest Solutions
, you can start the Application Trace Kit from the Start menu instead of from the command line.
Application Trace Kit Layout
The following graphic shows the layout of the Application Trace Kit.
Screen capture of Application Trace Kit layout.
The left area of the user interface has the following components:
  • Broker URL
    Lets you specify the URL to the broker.
  • Pathfinder
    Provides access to the following windows:
    • Live Paths
      Displays a snapshot of the live traffic captured by all the agents that are connected to the broker.
    • Saved Paths
      Displays the traffic that has been persisted to the 
      DevTest
      database.
    • Database
      Displays the structure of the 
      DevTest
      database and lets you make queries.
    • Tickets
      Displays any tickets generated in Application Insight.
  • Manage Agents
    Displays the agents that are connected to the broker.
  • Manage Consoles
    Displays the broker and the consoles that are connected to the broker.
If the
Manage Consoles
pane is not wide enough to display the broker and console names, the names are replaced by white space. Widen the pane until the names appear. Alternately, you can place the mouse pointer over the white space to display the names as tooltips.
The main area of the interface includes a toolbar. The toolbar changes depending on what you select in the left area:
  • If you select an item in the
    Pathfinder
    pane, the toolbar provides access to the associated windows.
  • If you select an item in the
    Manage Agents
    or
    Manage Consoles
    pane, the toolbar provides access to the associated management tools.
Live Paths
The
Live Paths
tab displays a snapshot of the live traffic captured by all the agents that are connected to the broker.
When you first view the traffic for an application in the
Live Paths
tab, you might find that the volume or granularity is not ideal. You can address these issues by modifying the agent configuration. For example, you can remove protocols from being captured or add protocols that are not currently being captured.
The following graphic shows multiple transactions in the
Live Paths
tab. One transaction is selected.
Screen capture of transactions in Live Paths tab.
The toolbar contains two refresh icons:
  • Show transactions currently in memory
    Show transactions currently in memory.png
    Displays the transactions that have been sent from one or more agents and are currently in memory. If the icon is gray, no new transactions are available to display. If the icon is blue, you can click the icon to display the latest transactions.
  • Time out partial transactions, flush them to the database and show transactions currently in memory
    Time out partial transactions.png
    Stops the agents from trying to stitch any transaction fragments into complete transactions.
Each node in the 
Component
 column represents a transaction frame.
The horizontal bars in the
Timing
column provide a visual indicator of the duration of each frame. For frames other than the root frame, the horizontal bars also indicate when the frame started and ended in relation to the root frame. A horizontal bar can include a vertical divider, which indicates the proportion of time that is spent in CPU compared to the wall clock time. You can view the time, duration, and CPU information by placing the mouse pointer over a horizontal bar.
To configure the amount of data that appears, click
Filters
. You can set each protocol to one of the following levels:
  • Hide
    Remove all frames for this protocol.
  • Collapse
    Merge multiple frames for this protocol at the same level.
  • View
    Display all frames for this protocol.
To view the agent and thread for a frame, place the mouse pointer in the first column.
When a transaction spans multiple agents, the first column uses different shading for each agent. The following graphic shows an example of this behavior for two agents.
Screen capture of shading in first column.
To view more information about a frame in the
Component
column, select the frame. One or more of the following tabs appear:
  • Details
    Displays basic information about the frame.
  • Request
    Displays the payload that was sent. The format varies depending on the protocol.
  • Request (Out)
    Displays the value of the arguments at the end of method execution.
  • Response
    Displays the payload that was received. The format varies depending on the protocol.
  • Screenshot
    Displays the image that is associated with a GUI event.
  • Debug
    Displays information that can be used for debugging.
    The initial rows contain the frame ID, the ID of the parent frame, the transaction ID, and the session ID. If the frame does not have a session ID, the value
    null
    appears.
If you enable profiling for an agent and then record some transactions, you can display the full call tree for any frame. Right-click the frame and select
Show call tree
.
You can filter the call tree by absolute duration and relative duration.
Saved Paths
The
Saved Paths
tab displays the transactions that have been persisted to the 
DevTest
database.
The following graphic shows the
Saved Paths
tab.
Screen capture of Saved Paths tab.
To view the full details of a transaction, double-click the transaction in the
Call
column. The window that appears is similar to the
Live Paths
tab.
To run the transaction again, do the following steps:
  1. Click the green arrow in the full details window.
    The
    Invocation
    window appears.
  2. (Optional) Change the parameters in the
    State
    ,
    Input
    , or
    Output
    tabs.
  3. (Optional) Change the selected agent.
  4. Click the green arrow.
Configure the Amount of Data Captured
You can configure the amount of data that a Java agent captures for each protocol. The following capture levels are available:
  • Discover
    Capture only the number of method invocations.
  • View
    Capture basic method information and timing.
  • Payload
    Capture all method information, including the request and response.
Follow these steps:
  1. Select the agent in the
    Manage Agents
    pane.
  2. Click
    Overview
    .
  3. Expand the
    Settings
    pane.
  4. Change the capture level for one or more protocols.
Configure Agent Properties
You can view and update the properties for a Java agent.
Follow these steps:
  1. Select the agent in the 
    Manage Agents
     pane.
  2. Click 
    Overview
    .
  3. Expand the 
    Settings
     pane.
  4. Change the value of one or more properties.
  5. To revert to the persisted settings, click
    Resync
    .
  6. To save the changes for the current session only, click
    Apply
    .
  7. To save the changes for the current session and future sessions, click
    Save
    .
View and Configure Logging
You can view the log messages for a Java agent.
The following example shows a partial set of log messages.
[DevTest AGENT:A][INFO][7336][166][ActiveMQ Session Task][04/28 14:04:39 (167)] Stopping Local CPU Profiling...
[DevTest AGENT:A][INFO][7336][167][ActiveMQ Session Task][04/28 14:05:39 (376)] Starting Local CPU Profiling...
[DevTest AGENT:A][INFO][7336][168][ActiveMQ Session Task][04/28 14:06:05 (204)] Setting weights: [com.itko.lisa.remote.transactions.interceptors.JDBCInterceptor: 4]
Follow these steps:
  1. Select the agent in the
    Manage Agents
    pane.
  2. Click
    Log
    .
  3. To filter out the messages below a certain log level, select the log level from the drop-down list.
View and Manage Classes
You can view and manage the full class hierarchy that is loaded in the Java virtual machine.
The following graphic shows an example of the class hierarchy. The
javax.ejb.EJBMetaData
interface is selected in the left pane. 
Screen capture of classes.
The
Metadata
tab contains the following information for the selected class or interface:
  • Method signatures
  • Superclasses or implemented interfaces
  • Subclasses or implementing classes
The
Source
tab lets you decompile the selected class or interface for debugging purposes only. When you click the
Source
tab, you must confirm that you have sufficient rights to view the decompiled code.
The Live Instances and OQL Queries lets you view objects that are currently live in your server.
Follow these steps:
  1. Select the agent in the
    Manage Agents
    pane.
  2. Click
    Classes
    .
  3. Select a class or interface in the left pane.
Manage Files
The Application Trace Kit includes a window that displays two sets of files:
  • Files on the local computer
  • Files on the computer where the selected agent is installed
You can perform file management tasks from this window.
Follow these steps:
  1. Select the agent in the
    Manage Agents
    pane.
  2. Click
    Explorer
    .
  3. To move a file from one computer to another, drag and drop the file.
  4. To open a file, double-click the file.
  5. To create new directories, delete files, and rename files, use the right-click menu.
Execute Remote Commands from the Terminal
The Application Trace Kit lets you display a command prompt or shell for the computer where the selected agent is installed.
You can perform any command that the operating system supports. For example, you can restart a process or check memory usage.
Follow these steps:
  1. Select the agent in the
    Manage Agents
    pane.
  2. Click
    Terminal
    .
CPU Profiling
By default, the 
DevTest
Java Agent captures only a subset of the traffic for an application. If you enable CPU profiling, the agent captures most or all of the traffic.
This feature is useful when you think that the agent is not capturing enough data or the right type of data for your purposes.
CPU profiling can impair the performance of the application. Therefore, we recommend that you enable this feature only on a temporary basis.
The following graphic shows the CPU profiling tab.
Screen capture of CPU profiling tab.
As in the
Live Paths
tab, the first column uses different shading for each agent.
The data that is also captured when CPU profiling is disabled appears in blue.
Follow these steps:
  1. Click the CPU profiling icon CPU profiling.png for one or more agents in the
    Manage Agents
    pane.
  2. Generate traffic and display the corresponding transactions in the
    Live Paths
    tab.
  3. Select a node in the tree.
  4. Click the
    Show profiling tree
    icon Show profiling tree.png.
    The CPU profiling tab appears.
  5. To view more information about a row, select the row. For most rows, only a limited amount of information is available.
Reinvoke a Transaction
You can create baselines from transactions in 
DevTest
Portal. The Application Trace Kit lets you reinvoke a transaction, which is similar to creating baselines. The advantage is that the process is quicker than creating baselines.
The following graphic shows the results of reinvoking a transaction. The expected response is the output that was originally recorded. The actual response is the output from reinvoking the transaction. The green square to the left of the
Actual Response
label indicates that the expected response and the actual response are identical.
Screen capture of reinvoking a transaction.
Follow these steps:
  1. Select a transaction in the
    Live Paths
    tab.
  2. Click the
    Invoke this transaction again
    icon Invoke this transaction again.png.
  3. Select the
    Output
    tab.
  4. Click the green arrow.
  5. If the square to the left of the
    Actual Response
    label is red, place the mouse pointer over the square to display information about the differences.