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 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.