dcpi - DIGITAL Continuous Profiling Infrastructure
The DIGITAL Continuous Profiling Infrastructure system consists of a set of tools that provides low-overhead continuous profiling of all executables, including the kernel. It is based on periodic sampling using the Alpha performance counter hardware. Profiles containing samples for each executable image (including shared libraries) are stored in a user-specified directory.
Tools are provided to analyze profiles and produce a breakdown of all cpu time by image, and by procedure within images. In addition, detailed information can be produced showing the time spent executing each instruction in a procedure and the reasons for static and dynamic stalls.
For more information, see the DIGITAL Continuous Profiling Infrastructure home page (http://www.research.digital.com/SRC/dcpi/).
- dcpid
- Continuous profiling daemon. Extracts raw samples from kernel device driver, associates them with executable images, and stores them in profiles on disk.
- dcpiprof
- Analyzes profile data collected by dcpid. Produces a breakdown of cpu time by image, or by procedures within images.
- dcpilist
- List the contents of a procedure and annotate the listing with samples collected during profiling via dcpid. The listing can contain either machine instructions, or source lines, or both. The listing is annotated with the samples collected during profiling, as well as the average number of cycles required to execute each instruction or source line.
- dcpicalc
- Annotates each instruction in a procedure's basic-block graph with the average number of cycles for that instruction, and computes the overall average cycle-per-instruction for that procedure.
- dcpiwhatcg
- Produces, for one or more images, a summary breakdown of where time has been spent (percent of cycles spent in, e.g., memory delays, static stalls, branch mispredicts, and useful execution).
- dcpitopstalls
- Produces a sorted list of the instructions accounting for the most stall cycles.
- dcpix
- Measure execution counts for basic blocks and control-flow edges directly; output can be used stall-analysis tools (dcpicalc, dcpiwhatcg, dcpitopstalls) to produce more accurate information. Without dcpix, these tools estimate execution counts.
- dcpisumxct
- Aggregates execution counts measured using dcpix from multiple runs of an instrumented program. This makes it possible for stall analysis tools to analyze counts from multiple runs of a program.
- dcpistats
- Compares multiple sets of raw sample counts and prints various statistics about them. Dcpistats is useful for comparing variations across multiple runs of the same program, or for comparing differences between slightly different versions of a program.
- dcpidiff
- Compares two sets of profiles for a procedure, highlighting basic blocks or source lines with the largest differences.
- dcpisource
- Augments a basic-block graph generated by dcpicalc with source code.
- dcpicc
- Compiles C programs to produce object code that helps dcpisource in identifying which source token each instruction corresponds to.
- dcpi2ps
- Formats a basic-block graph into Postscript.
- dcpi2pix
- Converts DCPI profile data to pixie format.
- dcpikdiff
- Creates a new image based on both vmunix and kmem(7) that captures the true running kernel image after Digital Unix dynamically patches itself using self-modifying code.
- dcpictl
- Controls the operation of dcpid. This subsumes dcpiepoch, dcpiflush, and dcpiquit (which are still provided for backward compatibility). Adds functionality to tell the daemon about specific images loaded into processes when necessary (e.g., when an image is loaded via mmap).
- dcpiepoch
- Starts a new profiling epoch. All samples are associated with a time interval called an epoch. The analysis tools typically operate on a set of profiles from a single epoch.
- dcpiflush
- Flushes all unsaved samples from dcpid to profiles on disk.
- dcpiquit
- Terminates the dcpid daemon, flushing all unsaved samples to disk.
- dcpiloader
- A modified version of the standard dynamic loader that provides dcpid with information about where executables are loaded.
- dcpiscan
- Scans filesystem directories to find executables and associate executables with filesystem pathnames.
- dcpiversion
- Print the version string and creation date of the installed DIGITAL continuous profiling release.
- dcpiuninstall
- Uninstalls DCPI binaries and man pages, and restores the original version of /sbin/loader.
- dcpicat
- Prints the contents of one or more profile files in an ASCII format.
- dcpiflow
- Generates a basic-block graph for a procedure annotated with samples collected during profiling via dcpid. The functionality of this program has been subsumed by dcpicalc.
- dcpidis
- Disassembles a procedure and annotates the disassembly with samples collected during profiling via dcpid. This program is obsolete. Use dcpilist instead.
Installation and Setup
See the DIGITAL Continuous Profiling Infrastructure home page (http://www.research.digital.com/SRC/dcpi/) for details of how to install the device driver, binaries, and man pages for the profiling system. Once the system is installed, dcpiscan should be run and one or more profile-database directories should be created.
- dcpiscan directories > map.local
- Create an image map for site-specific executables and shared libraries in the specified directories and their descendents. Although this step is technically optional, creating a map of local executables will allow dcpid to more accurately identify binaries stored in site-specific directories. Dcpiscan(1) should be executed once during system installation, and need only be re-executed to scan other directories or newly-installed executables.
- mkdir db
- Make a directory to store profiles.
The profiles written in the directory are owned by the user who invokes dcpid, so the directory must be writable by that user. If the directory is shared across hosts, its permission should be set appropriately to allow write-sharing by the users running dcpid. The directory must also be in a partition with a reasonable amount of available space (20 MB or so should be more than adequate).
Data Collection
After installation and setup are complete, data is collected by running dcpid and the tools that control it:
- dcpid -m map.local db
- Start the dcpid process; (If dcpid is not installed setuid-root as recommended, then this command must be run as root). The optional argument map.local should contain a mapping from executables to pathnames previously produced by dcpiscan; a default map for common DIGITAL Unix executables is compiled into dcpid. db is the database directory created during setup above.
- dcpiepoch
- Terminate the current epoch and start a new one, ensuring that profiles for the terminated epoch are flushed to disk and won't change.
- dcpiflush
- Flush buffered samples in the current epoch to the on-disk database. Note that this is typically not necessary; buffered samples are flushed to disk whenever an epoch is terminated and when dcpid is terminated. In addition, buffered samples are flushed periodically (at intervals that can be controlled with command-line arguments to dcpid).
- dcpiquit
- Terminate the current epoch, flushing all buffered samples to disk, and exit dcpid. This turns off all performance-counter interrupts and frees all memory used by the profiling system.
As dcpid runs, it creates subdirectories of db, one for each epoch. Each epoch directory further contains subdirectories, one for each platform sharing the same db. The platform names default to the local hostname on each machine running dcpid, so by default profiles collected on different machines are stored separately (though their epochs are synchronized). However, the file hosts in directory db may also be edited to contain a mapping from hostnames to arbitrary platform names, allowing samples from several hosts to be aggregated in the same profile database.
Data Analyais
After an epoch is terminated, the profile data for the epoch can be analyzed using a number of tools. By default, the analysis tools find the relevant profile files automatically. There are also a number of options that can be used to guide the search for profile files when the default rules are not appropriate; see the man pages for the individual tools for details.
- setenv DCPIDB db
- Set an environment variable that tells the downstream tools where the profile database is located.
- dcpiprof -i
- Use dcpiprof to analyze the breakdown of cpu time across all executables that ran during the epoch, broken down by image.
- dcpiprof I
- Use dcpiprof to analyze the breakdown of cpu time across all procedures in the image file I.
- dcpiwhatcg -stall "ITB/I-cache miss" I
- Identify the percentage of the CYCLES samples for image file I that were spent executing instructions vs. waiting for stalls of various categories; also produce a sorted list of the procedures in image file I based on the number of cycles spent waiting for ITB and I-cache misses in each procedure.
- dcpilist -asm P I
- Disassemble procedure P in the image file I, and annotate the disassembly with samples extracted from the profile database and the average cycle time required for executing each instruction.
- dcpilist -source P I
- Generate a source code listing of procedure P in the image file I, and annotate the listing with samples extracted from the profile database, and the average cycle time required for executing each source line.
- dcpicalc P I | dcpisource -f I.c | dcpi2ps -o P.ps
- Produce a basic-block graph for procedure P in image file I; then augment the graph with source lines from I.c, calculate the cycle per instruction for each instruction, and store the resulting Postscript in P.ps.
Installation instructions are at the DIGITAL Continuous Profiling Infrastructure home page (http://www.research.digital.com/SRC/dcpi/).
For processes that use the exec() system call (or its variants), PC samples are sometimes charged to the wrong image. Thus, it is possible to get samples for unexecuted instructions. Specifically, the problem is that samples gathered prior to an exec() call may be charged to an image that is running after exec() returns. This problem is not serious in practice for the common case of processes that call exec() once soon after being created: since there are only a few samples gathered prior to the exec(), only a few samples can be charged to the wrong image.
dcpiflow(1), dcpiprof(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).
This page was generated automatically by mtex software.Jennifer Anderson, Lance Berc, Jeff Dean, Sanjay Ghemawat, Monika Henzinger, Shun-Tak Leung, Mitch Lichtenberg, Dick Sites, Mark Vandevoorde, Carl Waldspurger, Bill Weihl.