Protrace Utility

(C) COPYRIGHT International Business Machines Corp., 1998
All Rights Reserved * Licensed Materials - Property of IBM

The Protrace utility allows you to filter the trace information contained in formatted trace files. Its features include:

• Filtering: Each entry in the trace is reduced to a single line (with the exception of raw data).
• Filtering: Entry and exit trace points are used to control indenting of the output. A separate indent is maintained for each thread in the trace.
• Formatting: Parenthesis are added to the output to allow editors such as vi to match entry and exit trace points.
• Filtering: Protrace is configurable. For example fields (e.g. PID) can be switched off.

Protrace Syntax
The syntax of the Protrace command is as follows:

Protrace inputfile [outputfile] [-t thread] [-i maxindent]  [-r] [-s(b,e,d,n,c,p,t,r)] [-inc stringlist | -exc stringlist]

inputfile is the output file from the showlog or Combtrace command. For example, the trace1.out file in the following showlog command could be the inputfile to the Protrace command:

showlog activity.log -debug > trace1.out 

outputfile, if specified, will cause the output to be sent to this file rather than to standard output.

You can, optionally, specify one or more of the following options with the Protrace command:

• -t only displays entries for the specified thread.
• -i specifies the maximum indent level. Set it to zero to disable indenting.
• -r includes any 'raw' data in the output.
• -s suppresses output as required. Append one or more characters to the -s as follows (e.g. -sedp) :
  • b disables parentheses.
  • e disables extended message.
  • d disables date/time.
  • n disables entry numbering.
  • c disables primary string cleaning.
  • p disables process Id.
  • t disables thread Id.
  • r disables the thread indent report generated after each run.
• -inc specifies a set of inclusion strings. The primary or extended message must contain at least one of these strings to be output. Separate each entry in the list with white space.
• -exc specifies a set of exclusion strings. The primary or extended message must NOT contain any of these strings to be output. Separate each entry in the list with white space.

Notes:

1. By default, open and close parentheses ({, }) are added to the output on entry and exit tracepoints, respectively. This allows bracket matching in editors such as vi.
2. By default, the primary message is cleaned prior to display. This involves the removal of certain string components as follows:
   • 'The function' from the start of the primary message
   • 'reported trace data.' from the end of the primary message
   • 'was entered.' from the end of the primary message (unless parentheses are disabled)
   • 'returned.' from the end of the primary message (unless parentheses are disabled)
3. By default, the output lines are numbered according to the corresponding trace entry in the source file.
4. Quotes can be used to specify inclusion or exclusion strings that contain white space.

Protrace Sample Output
The following is an example of Protrace's output:

Protrace trace.out -t 159 
----------------------------------------------------------------------------- 
#     Date   Time               PID   TID   PrimaryMessage : ExtendedMessage 
----------------------------------------------------------------------------- 
1     980626 134942.656056600 p:462 t:159  {OTSSubordinateRM::OTSSubordinateRM():159 : 
2     980626 134942.657705971 p:462 t:159    {OTSSubordinateRM::registerWithRecMgr(OTSSubordinateRM*):239 : 
3     980626 134942.659652866 p:462 t:159      {OTSSubordinateRM::initClass():205 : 
4     980626 134942.661251951 p:462 t:159        OTSMutex::OTSMutex(char*):90 :  _mutex_name = "_srmMutex",_lock_count = 0 
5     980626 134942.662932332 p:462 t:159      }OTSSubordinateRM::initClass():205 : 
6     980626 134942.664473589 p:462 t:159      OTSMutex::lock():152 :  rc = 0,_mutex_name = "_srmMutex",_lock_count = 1 
7     980626 134942.666307341 p:462 t:159      OTSMutex::unlock():186 :  rc = 0,_mutex_name = "_srmMutex",_lock_count = 0 
8     980626 134942.667986883 p:462 t:159    }OTSSubordinateRM::registerWithRecMgr(OTSSubordinateRM*):239 : 
9     980626 134942.669400750 p:462 t:159  }OTSSubordinateRM::OTSSubordinateRM():159 :

---------------------------------- 
ThreadNumber  IndentLevel  Verdict 
----------------------------------

159           0            Complete 
440           0            Complete 
532           1            INCOMPLETE 
535           0            Complete 
530           0            Complete 
529           0            Complete

Sorting the Protrace Output File
Since each trace file generated during the run of a server represents a separate asynchronous ORB request, the output from Combtrace may not to be in date/time order. If Protrace is used to process this output, it retains the entry ordering, and consequently the output from Protrace would not be in date/time order. If the -t option is not used to single out a particular thread of interest, this may make the output more difficult to read.

To compensate for this, the output from Protrace may be passed through a sort tool such as the UNIX 'sort' command. Note that Protrace outputs the date and time in a format that allows a numeric sort on the date and time fields to achieve correct date/time ordering.