SpyDoc.tioga
Michael Plass, September 22, 1992 1:13 pm PDT
Spy
CEDAR 10.1 FOR INTERNAL XEROX USE ONLY
Spy
A stack-tracing performance tool for PCedar
Michael Plass
© Copyright 1990, 1991 Xerox Corporation. All rights reserved.
Abstract: This is the data-collection part of the PCedar Spy. See the SpyTool for the data analysis.
Created by: Michael Plass
Maintained by: Michael Plass:PARC:Xerox
Keywords: performance measurement, tuning, memory allocations, timing, CPU usage
XEROX  Xerox Corporation
   Palo Alto Research Center
   3333 Coyote Hill Road
   Palo Alto, California 94304

For Internal Xerox Use Only
News
September 22, 1992 - added the ability to specify offsets when using SpySetTraceBreak.
December 13, 1991 - added the ability to spy on SIGNALs and ERRORs. New switches to SpyStart is -s.
June 28, 1991 - added the ability to turn the output of du (the UnixTM disk usage utility) into a spy log usable by the SpyTool. New command is SpyDUFilter.
May 17, 1991 - added the ability to spy on allocations and words allocated (without having to rely on setting breakpoints in the allocator). New switches to SpyStart are -a and -w.
Introduction
The Spy is designed to be the main tool for analyzing the performance of programs in PCedar. With the Spy, the programmer can see which procedures are consuming CPU cycles, which are using the allocator, or which are calling a particular procedure.
The main paradigm of the Spy is to record the call stack of an interesting process. The definition of "interesting" varies according to what the Spy is measuring. If the Spy is measuring CPU usage, it records the stack of the top-most active process at regular intervals. The only things recorded are the procedures in the call stack; parameters and local variables are not recorded.
The PCedar spy is a new implementation, based on the concepts of both the Interlisp Spy by Larry Masinter and the DCedar Spy by John Maxwell.
Commands
These commands may be used to start and stop the Spy from a Commander.
SpyStart Start the spy. Arguments:
-a  => watch allocations
-w => watch words allocated
-t  => watch thread switches (default)
-s => watch SIGNALs and ERRORs
-n <n> => preallocate n spy tree nodes (default 10000)
SpyStop Stop the spy, write results to specified file (or to standard out, if no argument is provided).
These commands are for setting spy breaks.
SpyClearBreaks Clear all spy breaks
SpySetTraceBreak <cprocname> - set a spy trace break
This command is a filter to add total counts to a disassembly listing:
SpyPCFilter Prepend counts onto disassembled code.
args: spy log name(s)
This may occasionally be useful for instruction-level tuning. The counts are cumulative, so tallys on call instructions include the samples for all the callees. (Self-calls will thus be overcounted).
This command turns the output of the du (the UnixTM disk usage utility) into a spy log usable by the SpyTool:
SpyDUFilter Convert output of du command into a spy log
Arguments are file names, output file names are suffixed with ".spy". An argument of "-" reads from standard input and writes to standard output.
Examples
% -- watch cpu usage
% SpyStart
% dosomething
Failed in PreRegister dosomething: No .command or .cm file found for dosomething
% SpyStop cpu.spy
% SpyTool cpu.spy
% -- watch allocations
% SpyStart -a
% dosomething
Failed in PreRegister dosomething: No .command or .cm file found for dosomething
% SpyStop allocations.spy
% SpyTool allocations.spy
% -- watch words allocated
% SpyStart -w
% dosomething
Failed in PreRegister dosomething: No .command or .cm file found for dosomething
% SpyStop wordsAllocated.spy
% SpyTool wordsAllocated.spy
% du . >exampledu
% SpyDUFilter exampledu
% SpyTool exampledu.spy
%
TraceBreak Examples
% SpySetTraceBreak ←XR←NewObject
Break set at pc=0008F6E3CH
% SpyStart -~t
% -- You probably want to say -~t when using breaks
% dosomething
Failed in PreRegister dosomething: No .command or .cm file found for dosomething
% spystop breaks.spy
% spytool breaks.spy
% SpyClearBreaks
Clearing break at pc=0008F6E3CH ...Ok.
%
It is on occasion useful to set the break a little bit into the procedure, so more meaningful information is available on the stack; for a SPARC, you want to be past the save instruction, which is usually the first or second instruction of a procedure. To do this, you may use an offset:

% Disassemble ←TransformOp←P2640 | head
PSGraphicsPrimitivesImpl.←TransformOp←P2640
00B8807C: 9DE3BF80 save %o6,-128,%o6
00B88080: F227A048 st %i1,[%i6+72]
00B88084: F427A04C st %i2,[%i6+76]
00B88088: F8062088 ld [%i0+136],%i4
00B8808C: 11002F4C sethi &hi(0x00BD3000),%o0 ! 0x00BD3000
00B88090: EE070000 ld [%i4],%l7
00B88094: D2062020 ld [%i0+32],%o1
{ 0.21 sec }
% SpySetTraceBreak ←TransformOp←P2640+4
Break set at pc=000B88080H
{ 0.01 sec }
% SpyStart -~t
{ 0.05 sec }
% dummyprint ppos112.ps
Opening ppos112.ps
0.39 elapsed seconds to alloc map and open ppos112.ps
Postscript file: ppos112.ps, spi: 300, copies: 1
Copy 1: [1]
Done in 18.81 (17.86) seconds (ppm: 3.2).

{ 19.40 sec }
% spystop ppos112.spy
{ 0.53 sec }
% spytool ppos112.spy
{ 0.25 sec }
% SpyClearBreaks
Clearing break at pc=000B88080H ...Ok.
{ 0.01 sec }
%
Client interface
Spy.mesa provides a client interface to the spy, in case somebody wants a different UI. Also, the use of Spy.SampleMyStack is a way to instrument code yourself.
See Also
SpyToolDoc.tioga tells you how to use a viewer-based tool for interpreting the results. SparcAidsDoc.tioga tells you about the Disassemble command.