[_CDCSL_93-16_]<1>Cedar>release>Spy>SpyDoc.tioga

SpyDoc.tioga

Michael Plass, September 22, 1992 1:13 pm PDT

Spy

CEDAR 10.1

Spy

A stack-tracing performance tool for PCedar

Michael Plass

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

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.