Linux Certif

Toute la documentation sur la certification Linux LPI

q-syscollect

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>.