NAMEq-syscollect - program to collect raw performance data from the system
SYNOPSISq-syscollect [-h] [-iku] [-c rate] [-C rate] [-t secs] [cmd] [args ...]
DESCRIPTIONq-syscollect is a program that collects profiles of kernel and user- space on Itanium-2 processors running recent (2.6.x, x > 4) Linux kernels. It uses the performance monitoring hardware built into the processor, and the pfmon subsystem of the Linux kernel. In addition to collecting profiles based on an event (default: CPU_CYCLES), it uses the branch-trace-buffers in the performance monitor to collect a call graph, so that a hierarchical profile can be generated. Profiles are put into a directory called .q. Each profile has sets of three files in that directory: PROGNAME-pidPID-cpuCPU.TYPE#VERSION where: PROGNAME name of the program whose profiles are in this file. PID the process id of the process profiled CPU the CPU that the process ran on. TYPE one of "info", "hist", or "edge": "info" contains general profile information, "hist" the execution-time histogram and "edge" the call-graph profile. VERSION a sequential version number, that gets incremented whenever there would be a filename collision otherwise; for example, with the NPTL thread-library, each thread in a multi-threaded program would get a separate version number. An example filename could be emacs-pid22148-cpu0.info#0. There is a separate file for each processor that a process executed on. In addition to profiles, the .q directory contains hidden files of the form .FILENAME.crc32.CRC, where FILENAME is the name of a file that is needed in order to analyse the profile data, e.g., the program executable, a shared library, or the kernel symbol table. CRC the crc32 checksum of the file's contents. By default, these files are symbolic links to the underlying files (except for /proc/kallsyms, which is always copied to .q to ensure availability of the proper symbols even when the machine gets rebooted with a different kernel). However, you can force the copying of such files by setting environment variable like so (assuming Bourne-shell syntax): Q_COPY_METHOD=copy export Q_COPY_METHOD This is useful when you expect to collect profiles on one machine and analyse them on another. By forcing copying, you can simply copy the entire .q directory to the analyzing machine and be assured that you got the right set of files to analyze the data with. Storing the checksum as part of these filenames serves two purposes: first, it ensures that filename collisions do not occur (i.e., we don't have to store the entire path of a file) and, second, it ensures that we have to maintain only one copy of each unique file which keeps disk- space consumption in check. Of course, with a good checksum, it would be sufficient to use just the checksum as the filename, but including the original filename can be helpful to get an idea what all those files are for.)
OPTIONSOptions follow the usual GNU command line syntax, with long options starting with two dashes ('-'). -h, --help Show summary of options. -c, --call-sample-rate rate Set the call sample rate to rate samples per second. This is the rate at which the branch-trace buffers are sampled to get a hierarchical profile. -C, --code-sample-rate rate Set the code sample rate to rate samples per second. The code sample rate is the rate at which the chosen event is sampled. -i, --monitor-interruptions Monitor code inside code regions that have interrupts masked. When using this mode, only basic blocks can be monitored, whereas in the usual case counts can be assigned to individual instructions. Also, to get best results, you need to apply a kernel patch available in the source package for q-tools (under q-syscollect/kernel-patches) to your kernel. -k,--monitor-kernel Include kernel samples in the profile. If this is specified without -u, it implictly turns -u off. -m, --merge-unknown=[on|off] Merge samples from unknown processes (default: on). -u, --monitor-user Include profiles from user-level code in the profile. If this is specified without -k, it implicitly turns kernel-mode collection off. -t, --sample duration time Collect samples for time seconds. -e, --code-sample-event EVENT Use EVENT to sample the code. Any single event from libpfm(3) can be specified. To get a full list of events, do pfmon -l.
SEE ALSOq-view(1), q-dot(1), pfmon(1).
AUTHORThis manual page was written by Al Stone <firstname.lastname@example.org>, for the Debian project with major improvements added by Peter Chubb <email@example.com>. March 7, 2005 Q-SYSCOLLECT(1)