PCT Frequently Asked Questions 0. What is the status of this document? A lot of this material pre-dates the dbctl generation of collectors which has very modest system requirements and very powerful capabilities. I've updated it a little, but mostly this document and others in the doc/ directory remain more useful in explaining the very low overhead library collectors. 1. What does PCT do? PCT collects and analyzes periodic sampling traces of program executions. This is an easy to implement profiling strategy that often yields all the information needed to optimize a program, or to decide that it cannot be fruitfully optimized. It is also a very low overhead mechanism. 2. How do I get started using PCT? On some OS's, you can just take any program or even shell script, compiled with (or less usefully without -g, but not stripped), and simply go: $ profile myprogram If you must re-link your binaries, the simplest mode of operation is to simply include /usr/lib/itimer.o (or wherever it is) on the link line. An alternative is to use /usr/lib/profil.o if your system doesn't support itimers, though profil.o cannot to profile usage of shared library code. You can then enable/disable profile data collection by the presence/absence of the PCT environment variable. So a three-liner usage example is: $ gcc foo.c /usr/lib/itimer.o $ PCT='' ./a.out $ pct line /tmp/pct/ct/a.out.*/* Provided 'myprogram' runs a "large" number of time quanta (usually 10 ms, though this can be fruitfully shrunken) this will yields a most informative breakdown of where 'myprogram' caused CPU time to be spent on the system. More details about various command line filters are/will be documented in separate man pages/documentation files. Documentation of the library facility is/will be in the man page for pct_on()/pct_off(). 3. What does "pct" or "PCT" stand for? Personally, and for the paper, I go with Profile Collection Toolkit. As with most such questions, "whatever you like" is a fine answer, too. There are several useful, if ambiguous/degenerate, mnuemonics I had in mind. The 'flat' nature of the profile generated suggests "Per CenT". This is reinforced by the literal output of profile formatting modules. "PC Timing" also sort of falls into this category. The style of data collection suggests "PC Timer", since a PC sampling timer goes off at specified intervals. The style of data collected suggests "Program/Profile CounTs/CounTers" or "Program Counter Times". Or "PC Times" or "Pc CTs", using the common cts abbreviation for counts. Etc, etc. I've even heard "PC Tracer/Tracker". The style of report generation suggests "Program Counting Toolkit/Toolbox", "Profile Collection Toolkit" and several other variants. "Profiling with Chuck's Toolkit" is even a possibility. :-) The plethora of suggested meanings of PCT which all end up being in the right vague meaning space made it seem like a good name. All programs, environment variables, and output files all have "pct" as a substring. So there's a lot of chances to memorize the abbreviation... 4. What system requirements does PCT have? PCT works, in some mode, on almost any Unix-like system. It has more or less functionality on various specific systems. On some systems, actually changing source code in main() might be necessary. On others LD_PRELOAD can be used to just switch on PC counting. Tweaking "arch.h" may be necessary to get things to compile/work for your particular system. On most, dbctl- based collection will just work for a single process or even a process tree, but may impose significant real-time overhead at high sampling rates. PCT is most useful on Linux, FreeBSD, OpenBSD, and others for which both LD_PRELOAD and libitimer.so work. All you need to do is set up $PCT and $LD_PRELOAD to track time in all program texts, shared libraries, and the kernel for entire process subtrees. Well, getting kernel profiling on may be a bit of a trick (a reboot or maybe recompiling and rebooting might be needed). Using information in /proc or from 'ldd' and the working LD_PRELOAD, PCT can enable profiling (note in a totally retroactive fashion) on any dynamically-linked executable and trace through any shared libraries loaded on startup. The utility of PC data may be poor for objects that have no symbols/debugging data. [ Some very simple hacks to the Linux/*BSD kernels could also allow time spent in dynamically loadable modules to be tracked, but that is future work. Some kernel or libc hacks could also allow a trap of the mprotect() call to dynamically add regions to the profiling system. ] Some PCT report generation scripts also require standard Unix utilities like 'nm', 'sed' and 'grep'. addr2line from the GNU binutils is very useful, but adb/gdb may be a substitute. 'nm -n' should be available on most systems, too. Etc. It's usually pretty obvious what is missing when it's not there. The scripts are quite short and easy to understand and modify. 5. Why do I get unresolved symbol errors when I use LD_PRELOAD=libprofil.so? Most likely you forgot to link your binary with "-Wl,-export-dynamic" or the equivalent for your OS. To know which region of virtual memory corresponds to your program text, libprofil.so must access the addresses of symbols which bound the text segment. Ordinarily 'ld' does not export the main text symbol table to shared libraries. This is what -export-dynamic reverses. It would be nice if this could be made a gcc/ld default? Hmm. 6. Why does my program take much more real-time to run when I enable PCT? The problem may be that the counter file resides on a network file system. Try using something like "PCT=o/tmp/test.pct". What is happening is that at each timer interrupt (every 1 ms .. 10 ms), the kernel updates one of the counters. This can cause your program to sleep for 0.1 .. 10 ms, if the kernel must wait for the write to complete. More recent network filesystems allow asynchronous updates and will likely be less suceptible to this effect. Nevertheless, local filesystems like /tmp are always safe. 7. Is there a GNU/FSF/X Emacs mode for PCT output? Actually, grep mode just works when addr2line/line number data is available. Just run 'pct' instead of grep. Depending on which grep mode we're talking about you might need pct ... | awk '{print $2 " " $1}'. When line number debugging data is not around, it would be nice to have a TAGS-like warping to function definitions. This would probably have to rely on TAGS being around. Anyways we aren't there yet.... 8. Is there a Vim Tags or syntax mode for PCT output? Not yet, but it should not be very different from existing modes. As usual, volunteer work is highly appreciated... 9. Does PCT depend on C/C++/Scheme/Lisp/Ada/Java/Your Favorite Language.../? No. Well, not exactly. PCT can be used with any system that provides some way to map program counters to source locations. This is usually synonymous with any language system that emits true object code and provides "source level debugging". 10. What is the history of PCT? Is it based on any other package? PCT was inspired by a package called 'bprof' for Linux by Bas de Bakker, but not even one line of code is borrowed. I had been using/hacking/porting bprof for going on 3 years. I was continually annoyed at his use of C++, especially STL dependencies, inappropriate sbrk() usage, bad error checking, lack of portability, and many other limitations. I accrued a list of ideas for the ultimate profiling package. I had a slow program to do congestion-based flow classification that I wanted to profile more. Rather than apply bprof again, I took a break from hacking on that and wrote up the basic library-package in one very intense week of hacking. Debugger-based sampling occurred to me early on, but at first all I had were some gdb scripts. Steve Bauer mostly figured out a clever fork following protocol, and did almost all the initial hacking on the config parser/dbctl. 11. What is the PCT copyright? Can I use it free of charge? PCT is Copyright (C) Charles L. Blake, 2000, 2001, 2002. You can use it free of charge. It would be payment enough if every program in the world ran just a little bit faster. You cannot, however, claim credit in any way, charge to redistribute the toolkit itself unless such distributions are also available for free via FTP or HTTP. You cannot change it and redistribute it unless you make your changes available to people. Standard GPL-like rules. I may just put all this under a GPL.