Provided by: q-tools_0.4-1_i386 bug

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)