caliper.1 (2010 09)

c
caliper(1)
Integrity Systems
caliper(1)
(Requires Optional HP Caliper Software)
conventions are followed) or a mixture of these languages.
You can specify the program to be measured using an absolute path, a relative path or a simple file name.
caliper searches $PATH when you specify a simple file name and looks in the current directory only if
$PATH includes it.
Alternatively, you can specify one or more already running processes to measure by listing their pid(s) on
the command line.
caliper will measure processes until they terminate, unless you use the
--dura-
tion option, or if you stop caliper by sending it a SIGINT (e.g., using Ctrl-C in a terminal window),
which will also generate a performance report or write performance data to a database.
Note that stopping
caliper with a SIGINT (Ctrl-C) when dynamic instrumentation is being used
(measurements
cgprof, fcount, and fcover) will cause caliper to immediately and forcibly ter-
minate all processes being measured before writing data. Using SIGINT with any other measurement
will stop
caliper while allowing measured processes to continue normally.
caliper can both collect data and optionally generate reports (in ASCII, CSV or any combination)
and/or create a
caliper database in a single run (using the syntax, "caliper measurement ...").
caliper can also:
• Generate a report from a previously created database (
caliper report),
• Merge or diff the data from multiple databases (
caliper merge and caliper diff),
• Analyze performance metrics from one or more previously created databases (
caliper advise), or
• Generate descriptions of reports and CPU events (
caliper info).
The measurement argument to the
caliper command is really the name of a measurement
configuration file which determines what measurement to make and how to make it. You can use the
standard measurement configuration files supplied with caliper or you can create your own. You can
also override measurement configuration file settings on the command line or in a
caliper initializa-
tion file (
.caliperinit).
One example of a measurement is
fprof, which tells caliper to collect the data needed to produce a
flat profile report based on CPU cycles.
Another example of a measurement is
dcache, which produces a report detailing where data cache
misses have occurred during execution of the program. See the EXAMPLES section for examples of using
fprof, dcache, and other measurements. See the Measurement Configuration Files section below for
more information on the supported measurements.
If an executable has been stripped of local symbols,
caliper can only report names for global functions.
If no symbol table (or debug information) exists at all, caliper will only report address information.
Like all performance measurement tools,
caliper can affect the runtime performance characteristics of
the program being measured.
Some measurements, such as
ecount, have negligible impact while dynamic instrumentation-based
measurements (
cgprof, fcount, fcover) can have a large effect. Take this "Heisenberg" effect into
consideration when interpreting any performance data.
When making measurements, performance data is always saved to a
caliper database. You can use
the --database option to specify the name and location of the database caliper creates.
If you do not use
--database, then the database (named for the type of measurement made) will be
saved in the ./.hp_caliper_databases directory (this default can be changed with the
CALIPER_DATABASES environment variable).
The most recently created measurement database is pointed to by an automatic "latest" symlink in the
CALIPER_DATABASES directory. If a simple database name is given on a caliper report or
advise run, then the CALIPER_DATABASES directory is searched after the current directory for the
database. So, caliper report fprof will report from the most recent fprof measurement run,
caliper report latest will report the latest measurement run of any type.
In addition to measuring and reporting performance data,
caliper can also analyze collected data and
make suggestions for improving your program’s performance. This analysis is driven by a set of rules
which look for specific data metrics indicating typical performance problems.
You can also write your own rules customized to your application. This is an iterative process where you
first make one or more
caliper performance runs saving the results in databases, run caliper
advise on those databases, review the suggestions, make changes to your program and/or how it is built,
HP-UX 11i Version 3: September 2010 − 3 − Hewlett-Packard Company 3