EVALPPLOG(1) User Commands EVALPPLOG(1) NAME evalpplog - evaluate personal process logs (time and defect logs) SYNOPSIS evalpplog [-01234] [-?] [-h] [-abcds] [-p] [-i] [-nt] [-m width] [-f {raw|std|tex|html}] [-- | file ...] DESCRIPTION evalpplog reads log files and outputs defect and interrupt listings and some statistics. If more than one file is given, the input data is treated as if all files were con- catenated. The lines in the log files may be event entries, extended entries or comments. The exact format of event entries is described in the following section. Empty lines and lines that start with whitespaces (tabs or spaces) are considered extended entries. These lines are ignored during evaluation. Lines with a special tag ('#' as default) as the first char- acters on a line, are recognised as comments. Lines with any other format are invalid. ENTRY FORMAT Event entries consist of a timestamp followed by tags describing the event. Tags are separated from each other by whitespaces, i.e. by blanks or tabs. The format of the timestamps has to match that of the timestamps in the exam- ples below. The first tag following the timestamp describes the type of event. The first character of this tag specifies whether the event starts ('b') or ends ('e'). The remaining characters may be the defect tag ('e'), the interruption tag ('i') or any other sequence of non-whitespace characters, which will be interpreted as a phase name. Unlike in older versions of evalpplog (called evalpsp) there are no default phase names, because all phases are treated the same. The interpretation of subsequent tags - the classification tags - depends on the type of event. Phase entries: All classification tags will be ignored. Jan 25 11:29:10 1998 bds This text will be ignored. Jan 25 12:12:52 1998 eds Ignored, too. Interrupt entries: Interrupts may be divided into classes using the first classification tag. All other classification tags will be ignored. If there are dif- ferent tags at the begin entry and the end entry, the tags of the end entry will be used. SunOS 5.5.1 Last change: 1998/10/26 (v1.7) 1 EVALPPLOG(1) User Commands EVALPPLOG(1) Jan 25 11:35:10 1996 bi phone_call (Peter) Jan 25 11:38:10 1996 ei This entry will be interpreted as an interrupt of type 'phone_call'. '(Peter)' is ignored. Jan 25 11:35:10 1996 bi phone call (Peter) Jan 25 11:38:10 1996 ei This entry will be interpreted as an interrupt of type 'phone'. The subsequent 'call (Peter)' is ignored. Defects entries: Defects may be divided into classes using any number of classification tags. A comment that is not to be interpreted may be added behind a separa- tor char, '#' being the default. During evaluation, all tags at the same position are considered to belong to the same classification category. By default, the first classification category represents the defect injection phase. Jan 25 13:00:00 1995 be Jan 25 13:02:00 1995 ee pl 30 - Com1 Jan 25 13:03:00 1995 be Jan 25 13:08:00 1995 ee cd 20 - Com2 Jan 25 13:09:00 1995 be Jan 25 13:14:00 1995 ee pl 20 - Com3 This example shows 3 defect entries with 2 classifica- tion categories. The classification tags 'pl' and 'cd' belong to category I, '20' and '30' to category II. You may choose classification categories and their individual entries in whichever way suits you, just use them consistently. You must not vary the number of classification categories within one input file. All events that are started must be ended. Interruptions must end before any other entry. New phases can only start when all previous phases, defects and interruptions are ended. Phases may not overlap; missing start or end entries are interpolated whenever unambiguously possible. Only defect entries may be nested. OPTIONS -h, -? Display about one screenfull of options, then exit. -0, -1, -2, -3, -4 This sets the "error sensitivity level" of evalpplog. Errors are missing or unrecognized tags, for example. SunOS 5.5.1 Last change: 1998/10/26 (v1.7) 2 EVALPPLOG(1) User Commands EVALPPLOG(1) -0 Print no warnings or errors at all. The results may be incorrect! -1 Print warnings on severe errors only. This is the default. -2 Print all errors and warnings. -3 Print all errors and warnings, die if severe errors are encountered. Use this option to safe-check your data. -4 Die if any errors are encountered. -a Print only advanced statistics, i.e. statistics show- ing relations between different defect classification categogies. -b Print only basic statistics, i.e. statistics showing data for one single classification category. -c Check for erroneous data only, don't output anything. Useful only in combination with -[2-4]. -d Print defect data only, no statistics. -s Print statistics only, no defect data. -p Do precise calculations (based on seconds). -i DON'T interpretate first defect classification tag as injection phase. By default, the first defect classif- ication category is considered to describe the phase where the defect was injected. -n DON'T print advanced statistics about number and per- centage of defects. -t DON'T print advanced statistics about defect duration. -m Truncate phase names and classes to 'width' characters when printing (default: 8). -f Select output format: RAW data, STanDard text format, laTEX format or HTML. -- Read a list of whitespace-delimited input filenames from STDIN and open these files for input. This may be helpful if you want to keep a list of files in order to evaluate them all at once. CUSTOMISATION evalpplog offers the possibility to add comments to any out- put table and to replace the automatically assigned classif- ication category names by useful names. Just have a look on SunOS 5.5.1 Last change: 1998/10/26 (v1.7) 3 EVALPPLOG(1) User Commands EVALPPLOG(1) the first source code lines. RELATED COMMANDS There is an emacs major-mode named pplog-mode which config- ures emacs to enter timestamps into a special log buffer upon pressing a specified key. These timestamps may then be decorated with phase tags and later on evaluated by evalpp- log. AUTHORS Oliver Gramberg (first version: evalpsp) Markus Middendorf (this ver- sion) Lutz Prechelt (corrections) Softwarelabor Karlsruhe SEE ALSO perl(1), emacs(1), pplog-mode.el, http://wwwipd.ira.uka.de/PSP/ BUGS Because evalpplog interpolates ends of interrupt or defect removal phases, at the time being you cannot decide to stop working on a defect, end the enclosing phase, and restart both on Monday next week. This is not very convenient, but can be worked around by introducing a (possibly named?) interrupt instead. Missing data may result in a "division by zero" error when calculating averages. Some characters have a special meaning in TEX or HTML and must be suitably quoted to appear correctly. Better avoid these characters altogether. SunOS 5.5.1 Last change: 1998/10/26 (v1.7) 4