dcpiprof(1)

NAME

dcpiprof - Analyze profile data collected by dcpid

SYNOPSIS

dcpiprof [-i] [-s event-type] [-keep percentage] [-p image-file-name] [-m map-file-name] [-no_header] [-full_output] [image-names...]

FLAGS

-i
Lists samples collected per image (instead of the default samples per procedure).
-s event
The named event type is used to sort the profile output. Otherwise, the output is sorted by cycles so that the procedure or image that accounts for the most cycles is listed first.
-keep p
Lists just enough top routines to account for the top p percent of the samples of the event type used to sort the profile output. The value p may be a floating point number in the range [0..100].
-p image-file-name
Use the specified image file as a candidate when associating profiles with named image files. This option can be repeated, allowing several image names to be specified on the command line.
-m map-file-name
Use specified map file generated by dcpiscan(1) for associating profiles with named images. This option can be repeated, allowing several map files to be specified; information from all of the supplied map files is merged. The -m option works like the -p option, except that instead of specifying one image at a time, a whole set of images can be entered into a map file via dcpiscan(1) and the entire set can be specified with one command line option.

A default map for common Digital Unix 3.2 and 4.0 binaries is compiled into dcpid; specifying additional maps will allow dcpiprof to find site-specific binaries.

-no_header
Do not print any header in the output. This option may be useful for programs that parse the output of dcpiprof.
-full_output
Prints extra information per line. This information may be useful for programs that parse the output of dcpiprof. The format of this extra information has not yet been documented because it is evolving.

PROFILE FILE FLAGS

By default, this command automatically finds all of the relevant profile files. The following options can be used to guide the search for the profile files.

-db <directory name>
Search for profile files in the specified profile database directory. The directory name should be the same name as the one specified when dcpid was started. I.e., the named directory should contain a set of epochs. If this option is not specified, the directory name is obtained from the DCPIDB environment variable. If neither this option, nor the DCPIDB environment variable are set, the name of the directory used by the last invocation of dcpid on this machine is used. If none of these methods succeed in finding the appropriate directory, and no explicit set of profile files is provided via the -profiles option, then the command fails.

-epoch latest
Search for profile files in the latest epoch. This is the default.

-epoch latest-k
Search for profile files in the "k+1"th oldest epoch. For example, search in the third last epoch if "-epoch latest-2" is specified.

-epoch all
Search for profile files in all epochs.

-epoch <name>
Search for profile files in the named epoch. The epoch name should be the name of a subdirectory corresponding to a single epoch within the profile database directory. Epoch subdirectory names usually take the form YYMMDDHHMM (year-month-day-hours-minutes). For example, an epoch started on December 4, 1996 at 23:34 is named 9612042334. If an epoch is given a symbolic name by creating a symbol link to the actual epoch directory, then the symbolic name can also be used as an argument to the -epoch option.

-events all
Search for profile files corresponding to all event types such as cycles, icache misses, branch mispredictions, etc. This is the default.

-events type(+type)*
Search for profiles files for the specified event types. For example, search for cycles, icache misses, and data cache misses when the option -events cycles+imiss+dmiss is specified.

-events all(-type)*
Search for profile files for all event types except for the specified types. For example, search for all event types except for branch mispredictions when the option -events all-branchmp is specified.

-label <label>
Search for profile files with the specified label (see dcpilabel). If no labels are specified on the command line, profile file labels are ignored entirely. If any labels are specified on the command line (this option can be repeated several times), only profile files that have one of the specified labels are used.

-profiles <file names...> --
Use just the profile files named by the specified file names. The list of profile file names can be terminated either via --, or by the end of the option list. The command prints an error message and fails if the -profiles option is used in conjunction with any of the earlier automatic profile finding options. (Use either the automatic profile lookup mechanism, or explicitly name the profile file with the -profile option, but not both.)

DESCRIPTION

Dcpiprof summarizes a set of profile files by printing a histogram of the number of samples per procedure (or the number of samples per image with the -i option.) The output is sorted by decreasing number of samples found within that procedure (or image). Each entry in the listing is annotated with the number of samples, the percentage of samples that belong to this entry, and a cumulative percentage value.

If some image names are specified on the command line, then only the profile files corresponding to the specified images are used to generate the output. Otherwise, if the -i option is specified and no image names are listed on the command line, then dcpiprof reads all profile files found in the profile database. If the -i option is not specified, and no images are listed on the command line, then dcpiprof prints an error message and exits.

Dcpiprof sometimes reports that it could not open some image files. In such cases, you can help dcpiprof locate the appropriate image files either by using the -p option to specify the name of an image file of interest, or by using the -m option to supply an image map generated by dcpiscan(1).

EXAMPLE USAGE

dcpiprof -i
Use dcpiprof to analyze the breakdown of cpu time across all images that contribute to the contents of the profile database.

dcpiprof <image names...>
Use dcpiprof to analyze the breakdown of cpu time across all procedures for the specified images.

dcpiprof -keep 99.99 ...
Stop the output after accounting for 99.99% of the samples.

INTERPRETING THE OUTPUT

Dcpiprof prints a header, followed by a number of lines of output. If per-image profiles are being produced, then there is a line per image, and the last column in the line is the name of the image. Otherwise there is a line per procedure and the last two columns contain the name of the procedure and the image to which the procedure belongs.

For example, consider the following output:

  Total samples for event type cycles   = 21761024463
  Total samples for event type imiss    = 1943063555
  
  The counts given below are the number of samples for each
  listed event type.
  ==========================================================
      cycles       %    cum%      imiss       % procedure       image
  9479311336  43.56%  43.56%   94570129   4.87% idle_thread     /vmunix
  3093399786  14.22%  57.78%  359058745  18.48% _XentInt        /vmunix
  2982861812  13.71%  71.48%   32386524   1.67% gh_zero_memory  /vmunix
  ...
This provides information on two different types of events: cycles events and imiss events (i.e., instruction cache misses).

The first three columns in each line contain information about the number of event samples that correspond to the event used to sort the dcpiprof output (cycles by default.) The first one of these columns lists the number of event samples that fell within this image/procedure (i.e. 9479311336 within idle_thread). The second column lists the percentage these event samples form of the total number of samples of this event type listed in dcpiprof's output (i.e. 14.22% of all cycle samples in dcpiprof's output fell within _XentInt). The third column gives the cumulative percentage of all event samples on this line and above (i.e. the top three procedures in the example account for 71.48% of the cycle samples.)

The remaining columns report the number of samples of other secondary event types. There are two such columns per secondary event type. The first column lists of the number of samples of that type (i.e. 94570129 imiss samples for idle_thread). The second column lists the percentage this number forms of the total number of samples of that type listed in dcpiprof's output (i.e. 18.48% of all imiss samples in dcpiprof's output fell within _XentInt).

OBSOLETE SYNTAX

If the environment variable DCPIPROF_OLDSYNTAX is set, dcpiprof emulates versions of dcpiprof older than 1.45. The old versions support the syntax:

    dcpiprof [options] [<profile file names...>]
I.e., the profile file names are specified explicitly on the command line, instead of via the profile file flags described earlier in this document. If no profile file names are listed on the command line, the names are read from standard input.

The old command line interface is supported for the use of old shell scripts. Users should just use the -profiles option if they need to specify profile file names explicitly.

SEE ALSO

dcpi(1), dcpiflow(1), dcpilist(1), dcpidis(1), dcpiscan(1), dcpiepoch(1), dcpiflush(1), dcpicalc(1), dcpilabel(1), dcpi2ps(1), dcpicat(1), dcpiquit(1), dcpidiff(1), dcpitopstalls(1), dcpiwhatcg(1), dcpictl(1), dcpisource(1), dcpicc(1), dcpiversion(1), dcpiuninstall(1), dcpi2pix(1), dcpikdiff(1), dcpix(1), dcpisumxct(1), dcpistats(1), dcpid(1), dcpiformat(4), dcpiloader(5)

For more information, see the DIGITAL Continuous Profiling Infrastructure project home page (http://www.research.digital.com/SRC/dcpi/ from outside DIGITAL).

COPYRIGHT

Copyright 1996-97, Digital Equipment Corporation.

AUTHOR

Sanjay Ghemawat, Monika Henzinger
This page was generated automatically by mtex software.