NAME
q-syscollect - program to collect raw performance data from the system
SYNOPSIS
q-syscollect [-h] [-iku] [-c rate] [-C rate] [-t secs] [cmd] [args ...]
DESCRIPTION
q-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.)
OPTIONS
Options 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 ALSO
q-view(1), q-dot(1), pfmon(1).
AUTHOR
This manual page was written by Al Stone <ahs3@debian.org>, for the
Debian project with major improvements added by Peter Chubb
<peterc@gelato.unsw.edu.au>.
March 7, 2005 Q-TOOLS(1)