SourceForge.net Logo
Home

ITRACE - Instruction Tracing

General Description

Running ITRACE

Related Documentation

General Description

ITrace (Instruction Trace) is a software tracing mechanism that runs on Windows and Linux. ITRACE is part of the performance tools packages. It uses the software trace facility (swtrace) to allocate a buffer, capture MTE information and write branch trace records. It then uses post to format the swtrace output into callflow reports. ITRACE traces through application and kernel code, and it can also trace IBM's Java jitted code.

How ITRACE works

ITRACE tracing gives you the ability to single step trace your application in Ring 3 and kernel code.
You can enable tracing of:
  1. All pids
  2. Only the current pid
  3. Only the given pid
  4. Only pids greater than the given pid
  5. Only pids from the given list of pids

ITRACE, in association with swtrace, A2N, and post can give you "arc" reports for your application. post can also dump the single step flow if needed (post -ss). ITRACE branch tracing works in concert with the software trace facility to trace ring 3 and ring 0 instructions. ITRACE uses the normal swtrace buffer and trace formats to record the last branch that executed. It uses the IA32/64 single step trap and branch flags to stop the application flow and write out a callflow hook. This hook includes time stamp, To and From addresses. ITRACE can also step through system calls, page faults and device drivers. When branch tracing through an application or system calls the machine is slowed down tremendously writing the instruction information to the buffer. This will change the characteristics of the system while tracing, to try and counter balance some of this we have added the ability to reduce the amount of timer ticks processed using a skip_count when tracing is turned on (currently not supported on Linux).

ITRACE tracing is turned on using two steps:
1) swtrace to setup the buffer and turn on trace options.
2) perfutil is used to invoke ITRACE enable/disable and on/off APIs.
The perfutil APIs use IOCTL calls to our device driver.

It is advisable to "warm-up" the code to be traced. This will reduce the amount of page fault processing that is traced. This is true in both C and Java code where the code path to be examined can be contained in a loop. Also note that with Java, the JIT code path will be traced the first "X" times that a method is jitted. It is advisable to try and keep the trace scenario as simple as possible and limit the amount of pids to trace.

Supported Environments

ITRACE Hooks

ITRACE writes two types of hooks to the swtrace buffer, one that contains branch information for every traced branch and the other when a traced pid changes.
It also uses the swtrace MTE hooks for post-processing name resolution.

Installation Procedure

For ITRACE support, install the platform appropriate package. See the Installing Performance Inspector page for available packages.

Running ITRACE


The following section assumes swtrace or swtrace.exe resides either in a directory listed in the PATH environment variable, or it resides in the current directory.

Initializing ITRACE

swtrace must be initialized using the swtrace init command. When swtrace is initialized, the required trace buffers (one per processor) are allocated in the kernel address space. The default buffer size is 3MB per processor, a larger buffer will be required to use ITRACE.

To initialize swtrace and initialize ITrace:

        swtrace init -s 30
        swtrace it_install
        swtrace disable


  

Collecting ITRACE Data


At this point swtrace has created the trace buffer(s) and initialized everything needed to start instruction tracing. The next step is to start the trace, by calling perfutil ITRACE APIs.

The suggested method of tracing would be to enable and turn on ITRACE in your application, as shown in the following sample C code: 

    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <stdint.h>

    #include "perfutil.h"

    int main(int argc, char* argv[])>
    {
       ITraceDisable();
       ITraceEnableCurrent();
       ITraceOn();

       // code to be traced
       ...

       ITraceOff();
    }

This code would trace the current pid/tid only.

ITRACE and Java

Java execution can also be traced, JPROF is used to gather Java naming and code information on jitted methods. post uses this information to "reconstruct" code execution of the jitted methods. To enable JPROF, start Java in one of the following ways:

Note: The jprof library must be in the appropriate paths.

You can enable/disable pids and turn on/off ITRACE directly from your Java application, using Java ITRACE APIs.

Capturing and Post-processing Trace Data

After tracing has completed and swtrace has been turned off, use the swtrace get command to extract the trace data from the trace buffer and copy it to disk. swtrace get copies the data in binary form to a file named swtrace.nrm2, by default. The data in swtrace.nrm2 is then post-processed using the post -arc command. post formats the trace data and produces a series of report files.

To capture the contents of the trace buffer to file swtrace.nrm2 and post-process it, enter:

        swtrace get
        post -arc

ITRACE swtrace Command Examples

swtrace init -s 50
This command will try to allocate a trace buffer of 50 MB per processor and initialize swtrace.

swtrace it_install
This command installs and initializes the ITRACE facility.

swtrace disable
This will deactivate all trace major codes.
 
swtrace on
This command turns on tracing.

greater 1 100
This program uses perfutil to start ITRACE. It will trace all pid/tids except the idle process.

swtrace off
This command will stop tracing.
 
swtrace get  mytrace.nrm2
This will extract the trace buffer into the file mytrace.nrm2.
 
post -r mytrace.nrm2 -arc
This will process the RAW file mytrace.nrm2 and generate an ASCII version in arc.
 
swtrace free
This command will free any swtrace buffers.
 
swtrace it_remove
This command will remove the ITRACE support.
 

Sample ITRACE Scenario using swtrace

 1.  Initialize swtrace                             swtrace init -s 10

     setting the buffer size to 10 MB per CPU.

 2.  Install ITRACE support.                        swtrace it_install
 
 3.  Disable all of the performance trace hooks.    swtrace disable  

 4.  Turn swtrace on.                               swtrace on
 
 5.  Run the desired program 
     with ITRACE enable/disable, on/off.            execute the program to trace

 6.  When ITRACE completes, or at the               swtrace off

     appropriate time, turn off swtrace.
 
 7.  Get a copy of the trace information            swtrace get
     from all processors.

 8.  If all tracing is complete, you could          swtrace free
     now free the trace buffers.

 9.  Generate readable trace data.                  post -arc -ss

 10. Remove ITRACE support.                         swtrace it_remove

post

post is used to format the swtrace buffer output, swtrace.nrm2 into codeflow reports. It can produce post.show, arc and ptree files. The ITRACE
options are -arc which creates an "arc" file. This is a generic2 file, which is a function call report. The -arc option along with the -ss option will produce the
function call report along with disassembled instructions. The "ptree" option will produce the prunned tree report which is a reduced callflow report.

See post documentation for more detail (also post -?). 

Home