caliper(1)caliper(1)NAMEcaliper - measure, report, and analyze program performance data
SYNOPSIS
measurement [collect_options] [report_options] program [program_args]
measurement [collect_options] [report_options] pid [pid]...
measurement [collect_options] [report_options]
[report_options] [database]...
[advise_options] [database]...
[info_options]
path_to_java]
Remarks
This command requires installation of the optional HP Caliper software,
which is not included in the standard operating system.
DESCRIPTION
The command measures, reports on, and analyzes the performance of
native Itanium(R) programs.
Quick Start
This section provides examples of common command invocations and fre‐
quently used options. Note that additional quick start help is avail‐
able from card located at:
and also downloadable from:
To make a sampled call-graph measurement and report results:
To measure and report sampled data cache misses:
To find a process's (for example, pid 1234) hottest functions over a
60-second period:
To find the hottest functions across the entire system (for both kernel
and processes) over a 120-second period:
To re-report the last measurement run with source and assembly code:
To analyze the latest performance runs and provide advice:
To see the difference between two collection runs of the same applica‐
tion:
To start the caliper GUI to interactively measure and explore perfor‐
mance data:
Common Measurements
cpu execution statistics
sampled call stack profile
cache miss profiles
total cpu event counts
flat execution profile
sampled call graph profile
Common Options
Save measurement results to named database:
Set length of measurement (in seconds):
Specify which cpu metric sets to measure:
where EVENT_SET is:
Specify which cpu events to measure:
Save textual performance report to file:
Selectively measure application processes:
Control reporting details:
Control the sampling specification for profiles:
Perform measurement system wide (not on specific processes):
Get help:
General Description
The command measures, reports on, and analyzes the performance of
native and Itanium(R) 2 programs. To obtain performance data, measures
some metrics using the Itanium's Performance Monitoring Unit (PMU) and,
on some platforms, measures other metrics by inserting probe code into
the running program. No special preparation of the measured program is
necessary.
is available on HP-UX 11i v2 and later and Linux/Itanium (2.6.5 kernel
and later). Note that not all features are available on all platforms;
see the section below for details.
operates in one of two broad collection modes: in per-process mode
(using or in system-wide mode (using
In per-process mode, tracks and measures individual processes, option‐
ally following and calls.
In system-wide mode, measures data across all CPUs on the system, and
then attributes samples to individual processes. Using system-wide
mode is a good way of understanding the broad performance picture on a
system, before "drilling down" using in per-process mode.
can measure programs which are built 32-bit or 64-bit, shared bound or
minshared bound, optimized or debug. Applications can be written in C,
C++, Fortran 9x, assembly (if standard runtime conventions are fol‐
lowed) 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. searches when you specify a sim‐
ple file name and looks in the current directory only if includes it.
Alternatively, you can specify one or more already running processes to
measure by listing their pid(s) on the command line. will measure pro‐
cesses until they terminate, unless you use the option, or if you stop
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 with a SIGINT (Ctrl-C) when dynamic instrumentation
is being used (measurements and will cause to immediately and forcibly
terminate all processes being measured before writing data. Using SIG‐
INT with any other measurement will stop while allowing measured pro‐
cesses to continue normally.
can both collect data and optionally generate reports (in ASCII, CSV,
HTML, or any combination) and/or create a database in a single run
(using the syntax, "...").
can also:
· Generate a report from a previously created database
· Merge or diff the data from multiple databases and
· Analyze performance metrics from one or more previously created
databases or
· Generate descriptions of reports and CPU events
The measurement argument to the command is really the name of a mea‐
surement configuration file which determines what measurement to make
and how to make it. You can use the standard measurement configuration
files supplied with or you can create your own. You can also override
measurement configuration file settings on the command line or in a
initialization file
One example of a measurement is which tells to collect the data needed
to produce a flat profile report based on CPU cycles.
Another example of a measurement is which produces a report detailing
where data cache misses have occurred during execution of the program.
See the section for examples of using and other measurements.
If an executable has been stripped of local symbols, can only report
names for global functions. If no symbol table (or debug information)
exists at all, will only report address information.
Like all performance measurement tools, can affect the runtime perfor‐
mance characteristics of the program being measured.
Some measurements, such as have negligible impact while dynamic instru‐
mentation-based measurements can have a large effect. Take this
"Heisenberg" effect into consideration when interpreting any perfor‐
mance data.
When making measurements, performance data is always saved to a data‐
base. You can use the option to specify the name and location of the
database creates.
If you do not use then the database (named for the type of measurement
made) will be saved in the directory (this default can be changed with
the environment variable).
The most recently created measurement database is pointed to by an
automatic "latest" symlink in the directory. If a simple database name
is given on a or run, then the directory is searched after the current
directory for the database. So, will report from the most recent mea‐
surement run, will report the latest measurement run of any type.
In addition to measuring and reporting performance data, can also ana‐
lyze 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 performance
runs saving the results in databases, run advise on those databases,
review the suggestions, make changes to your program and/or how it is
built, and repeat.
Note that because every program is unique, not all of the suggestions
will apply.
There are several defaults assumed when portions of the command-line
are omitted. If measurement is omitted, but either a program name or
process ID list is given, then the measurement is assumed. If is omit‐
ted, but a database is given, then is assumed. If is given, but no
databases are listed, then is assumed. Finally, if is given, but no
databases are listed, then all of the databases in the directory are
analyzed.
Finally, there is a full Graphical User Interface (GUI) available as an
alternative to the command-line user interface. The GUI can be used to
set up and make measurements as well as graphically explore collected
performance data. There are two ways to invoke the GUI:
· The first is to run it on the local machine with the command
· The second is to install a remote GUI client on a Windows or Linux
desktop system, run that program, and remotely connect to an
Integrity server on which the measurements will be made.
Measurement Configuration Files
The measurement argument to the command is actually the name of a mea‐
surement configuration file. Measurement configuration files determine
which measurements makes. You can use any of standard measurement con‐
figuration files or you can create and use your own.
The measurement parameter in the command line can be a simple, rela‐
tive, or absolute file name. If a simple file name is given, then
first looks in the current working directory for the file. If not
found, then looks in the directory. By default, is installed in on HP-
UX, and on Linux.
Many of the settings in the measurement configuration file can be over‐
ridden by their corresponding options on the command line.
Note that when making your own measurement configuration file, the
first line of the file must be a comment which begins with
to pass a validity check.
HP Caliper provides the following standard measurement configuration
files. Also see the section for additional platform-specific measure‐
ment configuration files that may be supplied.
Measures failed ALAT checks.
Measures branch (mis-)predictions.
Measures sampled call stack profile.
Measures sampled cycle profiles. Available only on dual-core
processors.
Measures data cache misses.
Measures data TLB misses.
Measures total cpu event counts.
Measures a flat profile of sampled instruction addresses.
Measures instruction cache misses.
Measures instruction TLB misses.
Collects per-(kernel)thread traces of sampled cache misses, TLB misses,
ALAT misses, branch mispredictions, instruction
addresses, and CPU events.
Creates a call graph profile using sampled branch data.
Profiles traps, interrupts, and faults.
Options
There are a number of command line options available which alter opera‐
tion. Option names and literal arguments can be abbreviated to their
shortest, non-ambiguous spelling. Although the command line synopsis
above shows options following measurement, in reality they can precede
and/or follow it.
In the option descriptions below, lower-case text (computer/bold font)
is a literal which is typed as shown and upper-case text (italics or
underline font) is descriptive and must be replaced with real values.
See below for additional options that may be available.
The following option can be used to supply options from a text file:
Specifies a text file
(OPTIONS_FILE) containing a list of command-line options (sepa‐
rated by spaces or newlines). You can also use an options file
to specify a measurement configuration file as well as the
application to be profiled and its arguments.
Data Collection Options
The command line options which affect data collection are:
EVT_PERIOD[CPU_EVENT[
Controls the branch sampling rate for an collection. See the
option below for argument details.
(Can also be specified with the
option.)
This saves measurement results to the named database.
Performance data is always saved to a database, whether one is
explicitly specified or not. If the option is used to specify
the explicit name and location of the database, then that data‐
base is used.
If the option is not given, then a database (named for the type
of measurement made) will be saved in the directory (this
default can be changed with the environment variable). The most
recently created measurement database is pointed to by an auto‐
matic "latest" symlink in the directory.
The optional qualifier will append the process ID of the HP
Caliper process to the name of the database it is writing to,
e.g.,
Valid only for the
measurement, this option specifies that should additionally
record (and report) global variables and process regions (stack,
heap, data, etc.) associated with data cache misses.
Specifies that additional information about each load module seen at
collection time is to be saved into the HP Caliper database.
This allows Caliper to correctly attribute displayed data, even
if the load modules are not available when a report is
requested.
Tells Caliper to save off symbol information about each load
module
into the database.
Saves off the executable text segment of each load module
into the database; this argument also implies the argu‐
ment.
Specifies that source line attribution data for each load module
should be saved into the database; this argument also
implies the and arguments.
This is a synonym for the
argument.
Specifies the bits to program the PMU's data address range matching
registers.
Forces event monitoring to be constrained by data address
ranges.
DBRP_INDEX can be 0, 1, 2 or 3. It identifies one of the four
Data Breakpoint Registers (DBRs) used to specify the desired
address range.
PLM specifies the privilege level setting. The privilege levels
available are: and
ADDR_MATCH is the 64-bit address to match. ADDR_MASK is the
56-bit address mask to apply before matching the ADDR_MATCH
bits.
PROC_FLAGS is comma-separated list of or as follows:
Indicates no constraint.
Indicates data address matching only.
Indicates instruction address and
opcode matching.
Indicates instruction address,
opcode and data address matching.
(Can also be specified with the
option).
Specifies how long the measured application should run (in sec‐
onds) before stops measuring it. When stops measuring, the
application is resumed and runs freely.
Specifies the default CPU event parameters. These apply to all
CPU events unless an event-specific setting is provided for the
given parameter.
EVENT_PARAM is defined as:
PLM determines the privilege level setting for a given metric.
By default, metrics are measured when your application runs in
user space. The privilege levels available are: and
THRESHOLD is an integer value that determines the semantics of
the counts reported by HP Caliper. When the threshold is zero
(the default), the reported count is the number of occurrences
of the event. When the threshold is not zero, the reported
count is the number of CPU cycles during which the number of
occurrences of the event met or exceeded the threshold.
Valid only for the
measurement, this option specifies the maximum number of frames
to unwind while collecting call stack samples. The default depth
is 32.
Specifies the bits to program the PMU's instruction address range
matching
registers. Forces event monitoring to be constrained by instruc‐
tion addresses ranges.
IBRP_INDEX can be 0, 1, 2 or 3. It identifies one of the four
Instruction Breakpoint Register pairs (IBRPs) used to specify
the desired address range.
PLM specifies the privilege level setting. The privilege levels
available are: and
ADDR_MATCH is the 64-bit address to match. ADDR_MASK is the
56-bit address mask to apply before matching the ADDR_MATCH
bits.
EVENT_SET] ...
CPU_EVENT] ...
(Can also be specified with the option.)
Specifies the event set or CPU events to measure. If no event
is specified (or is specified), then no metrics will be
reported. (Note: Specifying is not valid for the and measure‐
ments.)
EVENT_SET is a predefined collection of CPU events you specify
only with the measurement, (See below for more information.)
CPU_EVENT is a CPU event as recorded by the Performance Monitor‐
ing Unit (PMU) of the processor. You can change the default CPU
events recorded for any of the following measurements:
You can list CPU events available (along with descriptions) by
using (see below). Defaults specific to a given measurement can
be found in the measurement's configuration file.
EVENT_PARAM allows you to change the privilege level (default:
and threshold (default: 0) used when counting events. See above
for the syntax of EVENT_PARAM.
Specifies the default setting for load module inclusion in the measure‐
ment.
Specifies the load modules to be excluded from measurement. Module
names can be given as a simple file name which matches libraries
of this name in any directory; a full-path file name which
matches only this one specific library; or a full-path directory
name which matches all libraries within this directory or any
lower sub-directories.
Note that the trailing is required to distinguish a directory
name.
For instrumentation-based measurements the specified load mod‐
ules are not instrumented; for all other measurements, any sam‐
ples in the specified load modules are simply discarded.
Specifies the load modules to be included in the measurement.
Module names can be given as a simple file name which matches
libraries of this name in any directory; a full-path file name
which matches only this one specific library; or a full-path
directory name which matches all libraries within this directory
or any lower sub-directories.
Note that the trailing is required to distinguish a directory
name.
Specifies a list of directories to be searched when a load module file
(executable or shared library) cannot be found. A load module
may not be found if the measured process uses chroot(2) or
chdir(2) and then loads libraries or executes other binaries
using relative paths. (See also the entry for this option in
the section,
Specifies the bits to program the PMU's opcode matching registers.
Forces PMU
event monitoring to be constrained based on Itanium processor
encoding (opcode) of an instruction.
OPCODE_MATCH_CHANNEL is 0 or 1, where:
0 Corresponds to PMC 8 on Itanium, PMC 32 and 33 on Dual-Core
Itanium.
1 Corresponds to PMC 9 on Itanium, PMC 34 and 35 on Dual-Core
Itanium.
MFIB is a combination of characters to specify match slot
instructions:
Match M-slot
Match I-slot
Match F-slot
Match B-slot
OPCODE_MATCH is the opcode bits against which the instruction
encoding is to be matched. On Dual-Core Itanium, it an integer
of 41-bits or less. On Itanium, it is an integer of 27-bits or
less.
OPCODE_MASK is the mask bits to apply to the instruction encod‐
ing before matching the OPCODE_MATCH bits. On Dual-Core Ita‐
nium, it an integer of 41-bits or less. On Itanium, it is an
integer of 27-bits or less.
PROC_FLAGS is a comma-separated separated list of or as follows:
· and set the and bits of the opcode match register. These
bits are cleared by default.
· and will clear the corresponding bits in the opcode match
configuration register. These bits are set by default.
(Can also be
specified with the option).
Specifies which processes in an application's process tree
should be measured.
Use to measure only your application's root process.
Use to measure your application's root process and any processes
it forks.
Use (the default) to measure all your application's processes.
For more information, see below.
(Can also be specified with the
option).
Controls the sampling rate and the event that triggers
samples.
The first form is used only for the and measurements.
The second form is used for all other sample-based mea‐
surements etc.).
TIME_PERIOD is a sampling period in seconds, millisec‐
onds, or microseconds (specified as respectively, where N
is an integer).
For the measurement, the default TIME_PERIOD is 8ms of
CPU time (see also
For the measurement, the default TIME_PERIOD is 100 mil‐
liseconds (wall-clock time). Note that time is measured
in CPU cycles (for measurement) or real time (for mea‐
surement).
EVT_PERIOD specifies how many sampling events should
occur between samples.
VARIATION specifies how much to vary the number of events
between samples (may be specified as either an exact
count or as a percentage of the sampling rate if followed
by
CPU_EVENT specifies the CPU event to use for sampling.
You can list CPU events available (along with descrip‐
tions) by using (see below).
EVENT_PARAM allows you to change the privilege level
(default: and threshold (default: 0) in effect for the
CPU event counter used to trigger samples. See above for
the syntax of EVENT_PARAM.
Defines a measurement's scope.
PSET_LIST is defined as:
Caliper can measure activity on individual processes
scope), on all CPUs in the system scope) or, on HP-UX
systems, on all CPUs in selected processor sets scope).
The and scopes are supported for all PMU-based measure‐
ments The default scope is
With and scopes, the qualifiers and can be specified.
For measurements involving PMU samples, this determines
how such samples are attributed. is the default, and
tells to attribute samples to individual processes and
their load modules, whenever possible.
causes attribution simply to processes alone; specifies
no process attribution at all.
In all three qualifier cases, samples recorded in the
kernel will be attributed to kernel modules, if possible.
The option is a shortcut for
When the scope is the command-line arguments program and
program_args should not be provided. For more informa‐
tion, see below.
Reporting Options
The command line options which affect reporting are:
This option is valid when using the
and measurements. It specifies a cutoff value that lim‐
its hot call paths reported in Hot Call Paths sections.
Reporting of call paths stops when, for the given sort
metric, a call path is encountered whose associated met‐
ric percentage is below PERC_CUTOFF (default 1.0) or when
the CUM_PERCENT_CUTOFF has been met or exceeded (default
100.0).
The MIN_COUNT argument sets the minimum number of call
paths to be displayed (default: 5) regardless of the set‐
tings for PERC_CUTOFF and CUM_PERC_CUTOFF.
Specifies that function details should show at least
count_source source lines (default: 5 for source-only
reports or 0 for reports with disassembly code) before
and after reporting a source line entry with associated
performance data.
Set COUNT_SOURCE to to report all source lines for
reported functions. As with COUNT_SOURCE, set COUNT_DIS‐
ASSEMBLY to show context disassembly lines (default: 3).
Applies to PMU histogram reports only.
Specifies a file in which to write a
performance report in Comma-Separated-Values format (CSV)
for use in a spreadsheet or for further processing.
The file can be opened in or mode (default: Multi-process
reports can be generated (exec name is appended to each
file) or to a single, file (default: Specify to have the
process ID appended to the report file name.
Specifies how much detail to print in the per-process or
per application sections of every report (default:
prints information about the target application or
attached process measured.
reports basic time data about the execution.
reports the sampling parameters and counts.
lists the load modules that are part of the application
measured.
Specifies a cutoff value that limits functions reported in func‐
tion details
sections.
Reporting of functions stops when, for the given sort
metric, a function is encountered whose associated metric
percentage is below PERC_CUTOFF (default 1.0) or when the
CUM_PERCENT_CUTOFF has been met or exceeded (default
100.0).
The MIN_COUNT argument sets the minimum number of func‐
tions to be displayed (default: 0) regardless of the set‐
tings for PERC_CUTOFF and CUM_PERC_CUTOFF.
Applies to PMU histogram reports only.
Specifies how data for
processes and modules (those with matching basenames) is
combined in reports.
Specify to have data for matching processes combined
whenever possible. This is the default.
Specify to ignore individual processes, and create a
"module-centric" report for matching modules across all
measured processes.
Specify to combine no data across any processes.
Causes HP Caliper to append help information to the end of tex‐
tual reports.
Specifies the path to the kernel file you want HP Caliper to use
for symbol
lookup and disassembly.
This option only applies when kernel profiling is
involved, typically when the sampling specification for
the measurement has a privilege level mask of or
Specifies whether or not the latency bucket information should
appear in
reports (default:
This option is used only with the measurement.
Specifies a list of directories to be searched when a load mod‐
ule file
(executable or shared library) cannot be found.
A load module file may not be found if the load module is
not available from the location recorded at data collec‐
tion time.
(Can also be specified with the
option.)
Specifies the file writes its report to (default is std‐
out). The file can be opened in or mode (default:
Multi-process reports can be generated (exec name is
appended to each file) or to a single, file (default:
Specify to have the process ID appended to the report
file name.
Specifies whether or not
should report functions in one list (default: or report
functions grouped by load module
The following measurements support and
Specifies what types of percentages are shown in reports.
Specify to have a column showing percentage of samples
with respect to total number of samples taken.
Specify to have a column showing cumulative percentage of
samples.
Applies to PMU histogram reports only.
Specifies a cutoff value that limits processes reported in
process summary
section.
Reporting of processes stops when, for the given sort
metric, a process is encountered whose associated metric
percentage is below PERC_CUTOFF (default 2.0) or when the
CUM_PERCENT_CUTOFF has been met or exceeded (default
100.0).
The MIN_COUNT argument sets the minimum number of pro‐
cesses to be displayed (default: 5) regardless of the
settings for PERC_CUTOFF and CUM_PERC_CUTOFF.
Applies to PMU histogram reports only.
Specifies whether or not
should look for and read the initialization file
(default:
Caliper looks for a file in the current directory; if not
found, then looks in your home directory.
Settings in an initialization file take precedence over
measurement configuration file settings. Command-line
options take precedence over settings in an initializa‐
tion file.
(Can also be specified with the
option). For PMU histogram reports only. Specifies
level of program detail reported (default:
Specify to have data aggregated by source statement.
Specify to obtain reports at the lowest level of granu‐
larity available.
Specify to disable detail reports entirely. Specify to
print both source and instruction level details.
(Can also be
specified with the option). For function coverage
reports only. Specifies which coverage reports are pro‐
duced.
Default:
Specify for the load module summary report, for the
source directory summary report, for the source file sum‐
mary report, and/or for the function detail report.
Additionally specify to include functions from unknown
source files in the summary and detail coverage reports.
Specifies whether or not the hot call paths section should
appear in the call graph reports (default:
This option can be used only with the and measurements.
Valid only for
specifies functions that are of no interest. Call stacks
are not reported if their leaf routine is one of the
specified functions.
Specifies that performance data is to be sorted by values of
given metric.
(Default: See below.)
Specifies the
PATHMAP used in finding source files (used for reporting
source statements).
PATHMAP entries are separated by a colon and applied in
order until a file match is found.
Simple entries are prepended to file names; comma-sepa‐
rated entries specify to substitute the path to the left
of the comma with the path to the right of the comma.
Perl regular expressions are allowed in the left half of
a substitution.
Applies to PMU histogram reports only.
Specifies a cutoff value that limits functions reported in func‐
tion summary
sections.
Reporting of functions stops when, for the given sort
metric, a function is encountered whose associated metric
percentage is below PERC_CUTOFF (default 0.1) or when the
CUM_PERCENT_CUTOFF has been met or exceeded (default
100.0).
The MIN_COUNT argument sets the minimum number of func‐
tions to be displayed (default: 5) regardless of the set‐
tings for PERC_CUTOFF and CUM_PERC_CUTOFF.
Applies to PMU histogram reports only.
Specifies the system model number for reporting latency buckets
with the
measurement.
This option is necessary if you want HP Caliper to report
system-specific latency buckets on Linux. If you do not
use this option, a default set of latency buckets will be
used.
On HP-UX, HP Caliper automatically obtains the model num‐
ber using the command (see model(1)).
Specifies how thread data should be reported. Specify
to report data per thread. Specify to report data summed
across threads. Default:
Note that this option is currently only supported for the
following measurements:
Specifies which traps, faults, and interrupts
(collectively referred to as should report.
The traps measurement collects samples for 34 different
traps, but only 6 trap types can be shown in a single
report. You can re-report from the same HP Caliper data‐
base to see different sets of traps.
TRAP_NAME is is an abbreviation for a trap name. The
default TRAP_NAME values and their associated traps are:
Instruction TLB fault
Data TLB fault
Unaligned Data Reference fault
General Exception
Floating-Point Fault
Floating-Point Trap
For a list of all available values for TRAP_NAME, run the com‐
mand:
Advise Options
The command line options which affect advise-only runs are:
Specifies which classes of advice to report (default:
Every piece of advice is classified by which performance
area it apples to.
Specify one or more of for general advice, for advice
related to basic instruction execution, for memory-
related information, for input-output performance issues,
and/or for advice about items such as system calls. Only
advice in the selected classes will be printed.
Specifies how much advice to report. Each bit of advice has an
index value
reflecting its relative importance.
Advice is sorted with the most important items first and
the list stops when the index value of an item is below
MIN_INDEX (default: 5.0) or MAX_COUNT (default: 15) items
have been printed.
The MIN_COUNT (default: 5) argument sets the minimum
amount of advice to report regardless of the setting for
MIN_INDEX.
Specifies how much detail to report for each piece of
advice (default:
Each piece of advice may contain a brief description of
what it is focused on a suggestion for improving perfor‐
mance in this area additional performance measurements
which can be made to further explore this area a more
detailed explanation of what this performance area is and
the name of the rule generating this advice
Most rules will not have all of these components. One or
more of these can be given to limit what gets reported.
Specifies which executable program(s) to report on. By default,
all
executables which have performance data in the given
database(s) will be analyzed and a separate report pro‐
duced for each.
To analyze only selected executables, list them by giving
only their simple filename (no path information).
Specifies a list of files which contain the analysis rules to
use (default:
Only the rule files listed (and any rule files that they
include) will be used.
Each RULEFILE can be either a relative path, an absolute
path, or a simple filename. Simple file names are first
searched for in the current directory, then (if not
found) in the user's personal rules directory and finally
(if still not found) in the directory of the running
GUI Options
The command line options which affect the graphical user inter‐
face are:
(Can also be specified with the
option.)
Start the caliper GUI to interactively measure
and explore performance data.
Specify the location of the Java Runtime Environment (JRE) that
will run the GUI. If is not specified, will
first check if the environment variable is set to
a JRE; if not, will attempt to find a JRE via the
environment variable.
Information Options
The command line options which affect information-only runs are:
(Can also be specified with the
option.)
Specifies that information about the cpu counters which
match the given (partial) name or keyword be output.
The information fields to search are given with the
option.
The information fields to output are given with the
option. Use to report on all cpu counters.
The and options are mutually exclusive. If neither is
given, then is assumed.
(Can also be specified with the
option.)
Specifies which information fields to include in cpu
counter reports. It can be any combination of or sepa‐
rated by colons or
Default:
(Can also be specified with the
option.)
Specifies the file in which to write the information
report (default is stdout).
The file can be opened in or mode (default:
(Can also be specified with the
option.)
Specifies that information about the report types which
match the given (partial) REPORT_TYPE name be output.
This is the same information which is include in measure‐
ment reports when the option is used.
Report types are or
Use to report on all report types.
The and options are mutually exclusive.
(Can also be specified with the
option.)
Specifies which information fields are to be searched for
cpu counter reports. It can be any combination of or
separated by colons or
Default:
Help and Version Options
The following general options can be used to get syntax help or
print the version:
Prints the quick help text.
When used, must be used alone on the com‐
mand line.
Prints the long help text.
When used, must be used alone on the com‐
mand line.
Prints the version identification. When used, must
be used alone on the command line.
Specifying Settings with an Initialization File
You can save settings in a file, named that HP Caliper automati‐
cally uses at start-up. Putting the options in an initializa‐
tion file simplifies the command line you use to launch HP
Caliper.
For example, you can specify global settings for all of your
reports, such as system libraries to exclude and output file
locations. With your preferences in the initialization file,
you can then simply type:
The resulting report would use your predefined preferences.
Using this approach you could, for example, change your prefer‐
ences without having to change the HP Caliper command line in a
Note: Any option specified on the command line overrides the
corresponding setting in an initialization file.
There are a number of reporting options not available from the
command line that you can set in an option file. These are:
Specifies the maximum number of characters to print for branch
target
symbols in disassembly.
Default: 30
If statement-level data in reports is placed in parentheses.
Default: True
If no statement-level data will be reported.
Default: False
If no warnings will be issued if unrecognized variables are
detected in the initialization file or in measurement
configuration files.
Default: False
The initialization file can be in the current working directory,
your home directory, or in both locations. When you start HP
Caliper, it searches for the presence of an initialization in
this order:
1. in the current working directory
2. in your home directory.
and when finds one, it executes based on that initialization
file.
An initialization file is a Python script, similar to Caliper
measurement configuration file. Here is a sample file:
application="ls"
if caliper_config_file == 'branch':
process='all'
elif caliper_config_file == 'my_count':
application="/opt/mpi/bin/mpirun"
arguments = "-np 2 /proj/dynopt/test_fe/mpi_hello_world"
elif caliper_config_file == 'dcache':
application="/opt/mpi/bin/mpirun"
arguments = "-np 2 /proj/dynopt/test_fe/mpi_hello_world"
elif caliper_config_file == 'itlb':
application="/opt/mpi/bin/mpirun"
arguments = "-np 2 /proj/dynopt/test_fe/mpi_hello_world"
module_exclude="/usr/bin/sh"
The syntax inside the initialization file is the same as in mea‐
surement configuration files. In particular most long options
that are specified in the command line could be specified in the
initialization file, replacing the dash in the option long name
with underscore to form the variable name.
Process Selection
When dealing with multi-process applications, it is important to
be able to select processes to be measured in a process tree.
This section explains how to do this selection by using the
option.
Caliper has a choice between three behaviors when considering
what to do with a process:
The process is measured.
Caliper is informed of new processes gener‐
ated via or
The process is not measured.
Caliper is informed of new processes gener‐
ated via or
The process is not measured.
Caliper is not informed of new processes
generated via or
Caliper will pick which behavior is chosen depending on the
option. See below for additional information on process selec‐
tion.
This section uses the term process. The process is the process
at the root of the process tree. It is either the process
started by Caliper or the process to which Caliper attaches.
The simple options are:
Only the root process is measured.
Only the root process and processes forked from the root process
are measured.
Every process in the process tree is measured. This is the
default for all
measurements.
This option is available to be able to explicitly request the
default
behavior. This is equivalent to specifying for all mea‐
surements.
The complex options are:
Each argument provided to Caliper is interpreted as an addi‐
tional filter. Those filters are applied in order to
each new process. If a filter matches the process, the
behavior associated with the process is memorized.
Caliper will use the behavior of the last matching filter
to determine what to do with the process.
When no component is provided, the default interpretation
is as follows: the PATTERN component is interpreted as a
list of patterns separated by colons if the basename of
the executable matches any of those patterns, the process
is measured, otherwise it is tracked.
The presence of keywords in modifies those semantics as
follow:
Processes matching this filter will be measured.
Processes matching this filter will be tracked.
Processes matching this filter will be ignored.
The PATTERN is interpreted as a list of colon-
separated patterns.
The PATTERN is interpreted as a Python/Perl
regular expression that is tested using
the function (i.e., any non-empty match
will be considered a positive match).
The string used against the
PATTERN is the basename of the main exe‐
cutable of the process.
The string used against the
PATTERN is argument 0 of the process.
The string used against the
PATTERN is argument 1 of the process.
The filter only matches the root process.
The filter only matches processes created via
The filter only matches processes created by
For keyword families and only the last keyword used in
each family is considered. For the keyword family multi‐
ple keywords will be considered as specifying a logical
OR operation between the keywords.
The prefix is only necessary when no option is provided
and the PATTERN could be mistaken for one of the simple
options
Allows you to specify a Python function to be used as a filter
for
processes.
System-Wide Measurements
Only PMU-based measurements are available in system-wide mode
(across all CPUs in the system, instead of selected processes).
Measurements involving dynamic instrumentation see and are not
supported in system-wide mode. The measurement can occur at any
privilege level; the default privilege level for system-wide
mode is user and kernel space.
By default, samples are attributed to both a process and a load
module, whenever possible. Alternatively, you can specify (via
that samples be attributed to processes only or neither pro‐
cesses nor load modules. Both alternatives reduce the overhead
of collecting and reporting performance data.
(Note that attribution settings to do not affect attribution to
samples in the kernel.)
In addresses referring to user-space modules will not get
resolved regardless of the sample attribution requested.
HP Caliper cannot locate an executable or a shared library on
HP-UX if it is invoked using a relative path. In addition, at
certain times, executables and shared libraries cannot be
located even if they are specified with complete paths. If this
problem occurs, the result can be a large number of samples
reported as "unattributed". The workaround is to use the option
to specify a list of directories where the executables and
shared libraries are located.
Usage model:
· Replace the executable invocation with (or
· Define a measurement duration or measure until SIGINT (Ctrl-
C) is received.
On HP-UX, the option can be used to measure activity on all CPUs
belonging to the specified processor sets. For example,
measures activity on all CPUs in processor sets 1 and 2. You
can use the command (see psrset(1)) with the option to find pro‐
cessor assignment for all processor sets in the system.
Metrics for Sorts/Cutoffs
The following report types support the use of the following met‐
rics for sorting and applying cutoffs, where the default metric
for sorting is shown enclosed in [ ]:
(HP-UX only),
(HP-UX only)
By
default,
traps
are
always
sorted
on
the
first
trap
spec‐
i‐
fied
with
(or
ITLB
if
is
not
used).
Spec‐
i‐
fy‐
ing
sorts
based
on
val‐
ues
in
the
"Trap
Sam‐
ples"
col‐
umn.
Cut‐
off
set‐
tings
are
based
on
the
same
met‐
ric
as
the
sort,
by
default.
Use
or
to
over‐
ride
the
default
behav‐
ior.
EXTERNAL
INFLU‐
ENCES
Envi‐
ron‐
ment
Vari‐
ables
rec‐
og‐
nizes
the
fol‐
low‐
ing
envi‐
ron‐
ment
vari‐
ables:
spec‐
i‐
fies
the
data‐
bases
direc‐
tory
where
implicit data‐
bases
(those
not
spec‐
i‐
fied
with
a
option)
are
stored.
The
default
data‐
bases
direc‐
tory
is
Spec‐
i‐
fies
a
set
of options
which
are
used
for
every
mea‐
sure‐
ment
run.
The
con‐
tents
of
is
prepended
to
the
com‐
mand
line
before
it
is
pro‐
cessed.
It
is
pos‐
si‐
ble
to
spec‐
ify
all
argu‐
ments
and
options
via
PLAT‐
FORM-
SPE‐
CIFIC
ADDENDA
HP-UX
There
are
some
sit‐
u‐
a‐
tions
where
can‐
not
insert
probe
code
in
a
pro‐
gram
or
por‐
tions
of
a
pro‐
gram
due
to
non-
stan‐
dard
or
unusual
con‐
di‐
tions,
such
as
when
an
assem‐
bly
rou‐
tine
vio‐
lates
stan‐
dard
run‐
time
con‐
ven‐
tions.
In
such
sit‐
u‐
a‐
tions,
will
issue
warn‐
ing
mes‐
sages
and
pro‐
ceed
to
mea‐
sure
as
much
of
the
pro‐
gram
as
it
can.
The
fol‐
low‐
ing
addi‐
tional
mea‐
sure‐
ments
are
sup‐
plied
with
on
HP-
UX:
Mea‐
sures
call
graph
pro‐
file.
(This
is
an
enhanced
ver‐
sion
of
the com‐
mand.)
Mea‐
sures
per-
process
met‐
rics
based
on
sam‐
pled
CPU
events.
Mea‐
sures
func‐
tion
counts.
Mea‐
sures
func‐
tion
cov‐
er‐
age.
Pro‐
vides
a
wrap‐
per
for
Ktracer/Ktrace‐
dump
func‐
tion‐
al‐
ity.
See
also
the
HP
Caliper
Ktrace
Fea‐
ture
Guide.
The
fol‐
low‐
ing
addi‐
tional
options,
option
argu‐
ments,
or
option
fea‐
tures
are
avail‐
able
on
HP-
UX:
Spec‐
i‐
fies
the
bus
speed
in
MHz
for
the event
set.
If
you
spec‐
ify
the
sys‐
bus
event
set,
you
must
use
the
option
to
pro‐
vide
bus
speed.
The option
spec‐
i‐
fies
that
should
record
and
report
inline
func‐
tions,
if
data
is
avail‐
able
in
the
binary
to
dis‐
cover
such
inlines.
This
option
is
valid
only
when
using
the
cpu
mea‐
sure‐
ment.
Spec‐
i‐
fies
how
many sam‐
ples
(sam‐
pling
period
spec‐
i‐
fied
using
option)
will
be
aggre‐
gated
into
one
aggre‐
gated
sam‐
ple.
If
COUNT
is
0
or
1,
the
sam‐
ples
will
not
be
aggre‐
gated.
By
default
125
low-
level
sam‐
ples
will
be
aggre‐
gated
into
one
user-
reported
sam‐
ple.
This
option
is
valid
only
when
using
the
cpu
mea‐
sure‐
ment. Spec‐
i‐
fies
whether
to
print
all
7
sta‐
tis‐
ti‐
cal
met‐
rics
or
just
the
mean
and
stan‐
dard
devi‐
a‐
tion
con‐
trols
the
print‐
ing
of
each
sam‐
ple
in
addi‐
tion
to
report‐
ing
the
sum‐
mary
sta‐
tis‐
tics.
The
default
is
(report
only
the
mean
and
stan‐
dard
devi‐
a‐
tion
val‐
ues).
This
option
is
not
sup‐
ported
for and
runs.
The
option
is
only
valid
when is
spec‐
i‐
fied.
This
option
is
used
to
exclude/include
the
Caliper
process
activ‐
ity
as
part
of
the
mea‐
sure‐
ment.
The
default
is
(exclude).
Note
that
this
option
is
not
avail‐
able
on
Linux
and
the
behav‐
ior
there
is
equiv‐
a‐
lent
to
a
set‐
ting
of
(include
Caliper).
The
option
is
only
valid
when is
spec‐
i‐
fied.
This
option
is
used
to
exclude/include
the
idle
task
as
part
of
the
mea‐
sure‐
ment.
The
default
is
(exclude).
Note
that
this
option
is
not
avail‐
able
on
Linux
and
the
behav‐
ior
there
is
equiv‐
a‐
lent
to
a
set‐
ting
of
(include
the
idle
task).
The
default
ker‐
nel
path
used
is:
(HP-
UX
11i
v2
and
later).
Spec‐
i‐
fies
the
loca‐
tion
of
Ktracer
and
Ktrace‐
dump
bina‐
ries
to
be
invoked
from
Caliper.
Spec‐
i‐
fies
the
log‐
file
where
Ktracer
out‐
put
will
be
redi‐
rected.
Spec‐
i‐
fies
the
argu‐
ments
to
be
passed
to
the
Ktrace‐
dump
com‐
mand.
Spec‐
i‐
fies
the
argu‐
ments
to
be
passed
to
the
Ktracer
com‐
mand.
This
option
can
be
used
so
that
Ktracer
is
not
halted
(with
-h)
before
report‐
ing
the
data
with
Ktrace‐
dump.
This
option
can
be
used
so
that
Caliper
will
pro‐
ceed
with
a
Ktrace‐
dump
run
and
would
not
set
a
timer
or
wait
for
an
inter‐
rupt
from
the
user.
This
option
con‐
trols
whether
the
Ita‐
nium
PMU
is
enabled
while
pro‐
cess‐
ing
inter‐
rupts/traps.
means
that
the
PMU
is
enabled
all the
time
(dur‐
ing
reg‐
u‐
lar
pro‐
cess‐
ing
as
well
as
inter‐
rupt
pro‐
cess‐
ing).
means
that
the
PMU
is
only
enabled
dur‐
ing
reg‐
u‐
lar
pro‐
cess‐
ing and
dis‐
abled
dur‐
ing
inter‐
rupt
pro‐
cess‐
ing.
means
that
the
PMU is
enabled
dur‐
ing
inter‐
rupt
pro‐
cess‐
ing
and
dis‐
abled
dur‐
ing
reg‐
u‐
lar
pro‐
cess‐
ing.
The
default
is
for
and
cpu
mea‐
sure‐
ments.
The
default
is
or
the
fol‐
low‐
ing
mea‐
sure‐
ments
when
the
mea‐
sure‐
ment
scope
is
Note
that
this
option
is
not
avail‐
able
on
Linux
and
the
behav‐
ior
there
is
equiv‐
a‐
lent
to
a
set‐
ting
of
(PMU
is
enabled
dur‐
ing
reg‐
u‐
lar
pro‐
cess‐
ing
as
well
as
inter‐
rupt
pro‐
cess‐
ing).
Con‐
trols
the
col‐
lec‐
tion
and
report‐
ing
of
mem‐
ory
usage
data.
Cur‐
rent
mem‐
ory
use
can
be
mea‐
sured
at
any
or
all
of:
· the
begin‐
ning
of
the
run,
· peri‐
od‐
i‐
cally
through‐
out
the
run,
or
· at
the
end
of
the
run.
When
mak‐
ing
timed
mea‐
sure‐
ments,
cur‐
rent
mem‐
ory
use
is
sam‐
pled
every
PERIOD
num‐
ber
of
sec‐
onds
(default
if
no
qual‐
i‐
fier
is
given),
min‐
utes,
or
hours.
Only
sam‐
ples
which
show
a
dif‐
fer‐
ence
in
mem‐
ory
uti‐
liza‐
tion
from
the
pre‐
vi‐
ous
sam‐
ple
are
saved
and
reported
to
reduce
the
vol‐
ume
of
data.
No
mem‐
ory
usage
data
is
col‐
lected
or
reported
unless
the
option
is
used.
This
mea‐
sure‐
ment
can
be
made
in
con‐
junc‐
tion
with
any
Caliper
mea‐
sure‐
ment.
This
option
is
only
avail‐
able
on
HP-
UX
11i
v2
or
later
and
with
mea‐
sure‐
ment
runs.
Con‐
trols
the
type
of
data
col‐
lected
when
you
use
the
HP
com‐
pil‐
ers' option.
Choose
to
col‐
lect
arc
counts,
stride
data,
or
both
(depend‐
ing
on
which
have
been
enabled
at
com‐
pile
time).
Choose
to
col‐
lect
data
cache
miss
data.
Default:
Alter‐
na‐
tively,
you
can
choose
the
type
of
data
col‐
lected
by
assign‐
ing
or
to
the
envi‐
ron‐
ment
vari‐
able,
This
option
also
sup‐
ports
these
report
types: and
Con‐
trols
the
col‐
lec‐
tion
and
report‐
ing
of
sys‐
tem
usage
data.
Three
types
of
sys‐
tem
usage
data
can
be
col‐
lected:
(how
much
time
each
process
spent
run‐
ning,
eli‐
gi‐
ble
to
run
but
not
run‐
ning,
and
wait‐
ing),
(total
size
and
time
of
log‐
i‐
cal
and
phys‐
i‐
cal
I/O
done
by
each
process/thread),
(the
count
and
time
spent
in
every
syscall
called
by
a
process),
or
(the
default).
If
this
option
is
not
used,
both
and
are
col‐
lected
by
default.
Use
the
option
to
pre‐
vent
col‐
lec‐
tion
of
this
data.
This
mea‐
sure‐
ment
can
be
made
in
con‐
junc‐
tion
with
any
Caliper
mea‐
sure‐
ment.
This
option
is
only
avail‐
able
on
HP-
UX
11i
v2
or
later.
For
runs
involv‐
ing
the
Ita‐
nium
PMU,
spec‐
i‐
fies
whether
the
data
should
be
col‐
lected
for
the
entire
run
or
only
in
regions
delim‐
ited
by
the
PMU
enable/dis‐
able
instruc‐
tions
For
more
infor‐
ma‐
tion,
see
below.
When
attach‐
ing
to
a
process
to
per‐
form
or
mea‐
sure‐
ments,
the
depen‐
dent
shared
libraries
of
the
pro‐
gram
must
be
mapped
as
pri‐
vate
before
you
can
attach
to
the
process.
You
can
enable
pri‐
vate
map‐
ping
of
the
shared
libraries
by
using
the
com‐
mand
with
the
option
on
the
pro‐
gram
file
(see
chatr(1)).
When
attach‐
ing
to
a
process
for
or
runs,
will
remain
attached
to
the
tar‐
get
process
until
it
exits
(see
also
Stop‐
ping
with
the
use
of
SIG‐
INT
(e.g.,
Ctrl-
C
in
a
ter‐
mi‐
nal
win‐
dow)
for
and
runs
will
result
in
all
pro‐
cesses
being
forcibly
ter‐
mi‐
nated
after
Caliper
gen‐
er‐
ates
a
per‐
for‐
mance
report
or
writes
data
to
a
data‐
base.
Linux
The
fol‐
low‐
ing
option
is
avail‐
able
only
on
Linux:
Spec‐
i‐
fies
whether
the
tar‐
get
appli‐
ca‐
tion
should
be
blocked
when
the
PMU
sam‐
pling
buf‐
fer
is
full.
The
default
is
(in
other
words,
the
tar‐
get
appli‐
ca‐
tion
will
be
blocked
until
caliper
has
com‐
pleted
pro‐
cess‐
ing
all
the
sam‐
ples
in
the
buf‐
fer).
This
option
is
valid
only
for
PMU
based
per-
process
mea‐
sure‐
ments.
CPU
Met‐
rics
EVENT_SET
Descrip‐
tion
CPU
Met‐
rics
mea‐
sure‐
ment
type
requires
HP-
UX
11i
V2
Sep‐
tem‐
ber
2004
OE
(B.11.23.0409)
or
later.
You
can
spec‐
ify
the
event
sets
and
sam‐
pling
period
with
the
and
options,
respec‐
tively.
The
option
spec‐
i‐
fies
how
many
sam‐
ples
will
be
aggre‐
gated
into
one
aggre‐
gated
sam‐
ple.
You
can
mea‐
sure
mul‐
ti‐
ple
event
sets
in
the
same
run.
By
default,
the
met‐
rics
con‐
sist‐
ing
of
the
fol‐
low‐
ing
8
event
sets
will
be
mea‐
sured:
Exam‐
ple:
This
will
run
pro‐
gram,
mea‐
sur‐
ing
and
report‐
ing
the
fol‐
low‐
ing
met‐
rics
by
tak‐
ing
one
sam‐
ple
every
8
mil‐
lisec‐
onds:
By
default
125
low-
level
sam‐
ples
will
be
aggre‐
gated
into
one
user-
reported
sam‐
ple
result‐
ing
in
one
aggre‐
gated
sam‐
ple
col‐
lected
per
sec‐
ond.
The
result
is
saved
in
the
text
file,
You
can
spec‐
ify
one
or
more
comma
sep‐
a‐
rated
list
of
pre‐
de‐
fined
event
sets.
The
fol‐
low‐
ing
event
sets
are
avail‐
able.
is
the
default.
Pro‐
vides
infor‐
ma‐
tion
on
the
dynamic
mix
of
branch
types, branch
path
dis‐
tri‐
bu‐
tion,
branch
per
instruc‐
tion,
etc.
Pro‐
vides
met‐
rics
that
are
use‐
ful
in
assess‐
ing
the effec‐
tive‐
ness
of
branch
pre‐
dic‐
tion.
Pro‐
vides
met‐
rics
related
to
cache
coher‐
ence
activ‐
ity.
Pro‐
vides
met‐
rics
related
to
Cycles
Per
Instruc‐
tion
(CPI)
Pro‐
vides
infor‐
ma‐
tion
on
the
demand
that
a
spe‐
cific CPU
presents
to
the
CEC
chip
set,
and
the
demand
the
CPU
expe‐
ri‐
ences
due
to
the
CEC
traf‐
fic
ini‐
ti‐
ated
by
other
CPUs
or
I/O
com‐
po‐
nents
in
the
sys‐
tem.
Pro‐
vides
met‐
rics
on
the
effec‐
tive‐
ness
of
con‐
trol
spec‐
u‐
la‐
tion.
Pro‐
vides
qual‐
i‐
ta‐
tive
view
of
the
par‐
al‐
lel‐
ism
that
is avail‐
able
as
seen
at
instruc‐
tion
dis‐
per‐
sal.
Pro‐
vides
met‐
rics
on
the
effec‐
tive‐
ness
of
data
spec‐
u‐
la‐
tion.
Pro‐
vides
miss
rate
infor‐
ma‐
tion
for
the
L1
data
cache.
Pro‐
vides
miss
and
prefetch
usage
infor‐
ma‐
tion
for
the L1
instruc‐
tion
cache.
Pro‐
vides
miss
rate
infor‐
ma‐
tion
for
the
L2
uni‐
fied
cache. Not
avail‐
able
on
dual-
core
pro‐
ces‐
sors.
Pro‐
vides
miss
rate
infor‐
ma‐
tion
for
the
L2
data
cache. Only
avail‐
able
on
dual-
core
pro‐
ces‐
sors.
Pro‐
vides
miss
rate
infor‐
ma‐
tion
for
the
L2
instruc‐
tion
cache. Only
avail‐
able
on
dual-
core
pro‐
ces‐
sors.
Pro‐
vides
miss
rate
infor‐
ma‐
tion
for
the
L3
uni‐
fied
cache.
Pro‐
vides
an
over‐
view
of
pro‐
ces‐
sor
activ‐
ity
by
col‐
lect‐
ing
mul‐
ti‐
ple event
sets.
On
non-
dual-
core
pro‐
ces‐
sors,
the
event
sets
used
are:
On
dual-
core
pro‐
ces‐
sors,
the
event
sets
used
are:
Note
that,
on
dual-
core
pro‐
ces‐
sors,
spec‐
i‐
fy‐
ing
is
equiv‐
a‐
lent
to
spec‐
i‐
fy‐
ing:
Pro‐
vide
BRQ
(Bus
Request
Queue)
met‐
rics
that
may
give some
insight
into
pos‐
si‐
ble
sys‐
tem
bus
related
per‐
for‐
mance
prob‐
lems.
Pro‐
vides
met‐
rics
on
pri‐
mary
CPU
per‐
for‐
mance
lim‐
iters by
break‐
ing
the
CPI
into
seven
com‐
po‐
nents.
Pro‐
vides
met‐
rics
on
sys‐
tem
bus
uti‐
liza‐
tion. If
you
spec‐
ify
the
sys‐
bus
event
set,
you
must
use
the
option
to
pro‐
vide
bus
speed
in
MHz.
For
exam‐
ple,
Pro‐
vides
met‐
rics
related
to
TLB
misses.
Pro‐
vides
met‐
rics
on
hyper‐
thread‐
ing
thread
switch
behav‐
ior. Only
avail‐
able
on
dual-
core
pro‐
ces‐
sors.
Lim‐
it‐
ing
PMU
Mea‐
sure‐
ment
For
mea‐
sure‐
ments
that
involve
the
Ita‐
nium
PMU,
you
can
restrict
mea‐
sure‐
ments
to
spe‐
cific
parts
of
your
appli‐
ca‐
tion.
The
sup‐
ported
mea‐
sure‐
ments
are:
By
default,
HP
Caliper
mea‐
sures
PMU
events
for
your
entire
pro‐
gram.
How‐
ever
using
allows
you
to
restrict
mea‐
sure‐
ments
to
per‐
for‐
mance-
sen‐
si‐
tive
regions
of
code.
To
use
this
fea‐
ture:
· Mod‐
ify
the
appli‐
ca‐
tion
source
code
to
use
the
header
file
pro‐
vided
with
HP
Caliper.
The
default
loca‐
tion
of
the
header
file
is
· In
your
source
code,
add
the
HP
Caliper
macros
to
enable
and
dis‐
able
the
Ita‐
nium
PMU.
· To
enable
the
PMU,
insert:
Using
enables
the
PMU
for
the
cur‐
rent
thread
until
the
next
When
the
PMU
is
already
enabled,
does
not
have
any
effect.
· To
dis‐
able
the
PMU,
insert:
When
the
PMU
is
already
dis‐
abled,
does
not
have
any
effect.
· Use
the
com‐
mand-
line
option
or
place
in
a
mea‐
sure‐
ment
con‐
fig‐
u‐
ra‐
tion
file.
This
option
causes
HP
Caliper
to
allow
the
mea‐
sured
appli‐
ca‐
tions
to
con‐
trol
the
PMU.
When
spec‐
i‐
fied,
the
PMU
is
ini‐
tially
dis‐
abled
and
HP
Caliper
will
not
mea‐
sure
the
appli‐
ca‐
tion
until
the
first
is
exe‐
cuted.
If
you
do
not
spec‐
ify
the
option,
and
do
not
have
any
effect
and
the
instruc‐
tions
behave
as
no-
ops.
Met‐
rics
for
Sorts/Cut‐
offs
Spe‐
cific
to
HP-
UX
Here
is
addi‐
tional
infor‐
ma‐
tion
on
"Met‐
rics
for
Sorts/Cut‐
offs"
spe‐
cific
to
HP-
UX.
The
fol‐
low‐
ing
addi‐
tional
report
types
sup‐
port
the
use
of
the
fol‐
low‐
ing
met‐
rics
for
sort‐
ing
and
apply‐
ing
cut‐
offs,
where
the
default
met‐
ric
for
sort‐
ing
is
enclosed
in
[ ]:
Addi‐
tional
Envi‐
ron‐
men‐
tal
Vari‐
able
on
HP-
UX
The
fol‐
low‐
ing
addi‐
tional
envi‐
ron‐
ment
vari‐
able
is
avail‐
able
on
HP-
UX:
Spec‐
i‐
fies
the
(non-
default) caliper_root
loca‐
tion
when
is
auto‐
mat‐
i‐
cally
invoked.
This
is
only
needed
when
is
not
installed
in
its
default
loca‐
tion
and
a
pro‐
gram
com‐
piled
with
the
option
(pro‐
file
based
opti‐
miza‐
tion)
is
run.
Lim‐
i‐
ta‐
tions
The
cur‐
rent
HP-
UX
ver‐
sion
of
has
the
fol‐
low‐
ing
lim‐
i‐
ta‐
tions:
· Only
aggre‐
gated
results
can
be
pro‐
duced
for
multi-
threaded
pro‐
grams
by
the
and
mea‐
sure‐
ments.
· Hand‐
writ‐
ten
assem‐
bly
func‐
tions
which
do
not
fol‐
low
the
stan‐
dard
lan‐
guage
run‐
time
con‐
ven‐
tions
may
not
be
prop‐
erly
mea‐
sured
for
instru‐
men‐
ta‐
tion-
based
reports:
and
· Only
native
Ita‐
nium
pro‐
grams
pro‐
duced
by
the
HP
C,
C++
and
For‐
tran
9x
com‐
pil‐
ers
can
be
mea‐
sured.
PA-
RISC
pro‐
grams,
although
they
can
run
on
Ita‐
nium
sys‐
tems,
can‐
not
be
mea‐
sured.
· The
option
is
only
sup‐
ported
on
HP-
UX
B.11.23.0409
or
later.
· The
option
can
not
be
used
while
any
other
PMU
mea‐
sure‐
ment
is
run‐
ning
on
the
sys‐
tem.
· The
option
can
only
be
used
by
priv‐
i‐
leged
users,
unless
this
secu‐
rity
mea‐
sure
is
dis‐
abled
by
set‐
ting
the
ker‐
nel
tun‐
able
to
the
value
1.
· DLKM
com‐
po‐
nents
are
only
listed
if
the
user
is
priv‐
i‐
leged.
Func‐
tion-
level
infor‐
ma‐
tion
is
not
avail‐
able
for
those
mod‐
ules.
LINUX
There
is
no
default
ker‐
nel
path
used
when
sam‐
pling
is
done
while in
ker‐
nel
mode.
By
default,
only
ker‐
nel
mod‐
ule
and
func‐
tion
infor‐
ma‐
tion
is
pro‐
duced
for
sam‐
ples;
this
option
must
be
used
to
dis‐
play
dis‐
as‐
sem‐
bled
instruc‐
tions
for
ker‐
nel
mod‐
ules.
Lim‐
i‐
ta‐
tions:
The
cur‐
rent
Linux
ver‐
sion
of
has
the
fol‐
low‐
ing
lim‐
i‐
ta‐
tions:
· Cor‐
re‐
lat‐
ing
sam‐
ple
data
to
source
files
cre‐
ated
with
GNU
com‐
pil‐
ers
requires
debug
infor‐
ma‐
tion
cre‐
ated
with
the
com‐
piler
option.
EXAM‐
PLES
Here
are
some
exam‐
ples
of
com‐
mon
uses
of
This
will
run
pro‐
gram,
mea‐
sur‐
ing
and
report‐
ing
the
total
num‐
ber
of
Ita‐
nium
instruc‐
tions
exe‐
cuted
(IA64_INST_RETIRED),
the
total
num‐
ber
of
nops
exe‐
cuted
(NOPS_RETIRED)
and
the
total
num‐
ber
of
CPU
cycles
expended
(CPU_CYCLES).
This
will
run
pro‐
gram,
mea‐
sur‐
ing
and
report‐
ing
the
num‐
ber
of
Ita‐
nium
instruc‐
tions
exe‐
cuted
(IA64_INST_RETIRED),
the
num‐
ber
of
nops
exe‐
cuted
(NOPS_RETIRED)
and
the
num‐
ber
of
CPU
cycles
(CPU_CYCLES)
every
10,000
cpu
cycles
(with
no
sam‐
pling
vari‐
a‐
tion.
The
mea‐
sure‐
ment
default
is
to
sam‐
ple
every
50,000,000
cpu
cycles.
This
will
run
pro‐
gram,
mea‐
sur‐
ing
and
report‐
ing
a
flat
pro‐
file
of
sam‐
pled
instruc‐
tion
addresses,
exclud‐
ing
all
sys‐
tem
libraries.
This
will
run
pro‐
gram,
mea‐
sur‐
ing
and
report‐
ing
a
call
stack
pro‐
file
by
peri‐
od‐
i‐
cally
sam‐
pling
the
appli‐
ca‐
tion
pro‐
gram
counter
and
each
of
its
thread's
call
stacks.
This
will
re-
report
the
last
mea‐
sure‐
ment
run
with
all
func‐
tions
included
in
the
report
(no
mat‐
ter
how
lit‐
tle
CPU
time
they
used).
This
will
pro‐
duce
an
infor‐
ma‐
tion
report
includ‐
ing
all
details
on
all
cpu
events
with
"L2"
in
name.
This
will
pro‐
duce
an
infor‐
ma‐
tion
report
on
the
itlb
mea‐
sure‐
ment
report.
This
will
col‐
lect
all
activ‐
ity
across
all
CPUs
in
the
sys‐
tem
for
a
dura‐
tion
of
10
sec‐
onds,
pro‐
duc‐
ing
a
sam‐
ple-
based
call
graph
report.
This
will
mea‐
sure
and
exe‐
cu‐
tions.
This
will
mea‐
sure
both
/usr/bin/ls
and
/usr/bin/echo
pro‐
cesses.
This
will
mea‐
sure
both
and
pro‐
cesses.
This
will
mea‐
sure
both
the
and
pro‐
cesses,
since
the
reg‐
u‐
lar
expres‐
sion
matches
their
argu‐
ment
1.
This
will
cre‐
ate
a
report
with
the
dif‐
fer‐
ence
between
the
data
col‐
lected
in
the
two
col‐
lec‐
tion
runs.
This
will
ana‐
lyze
the
data
in
HP
Caliper
data‐
bases
DB1
and
DB2,
and
make
sug‐
ges‐
tions
for
per‐
for‐
mance
improve‐
ments.
HP-
UX
ONLY
EXAM‐
PLES
This
will
run
pro‐
gram,
mea‐
sur‐
ing
and
report‐
ing
an
extended
call
graph
pro‐
file.
AUTHOR
HP
Caliper
was
devel‐
oped
by
the
Hewlett-
Packard
Com‐
pany.
FILES
caliper_root Anchor
loca‐
tion
of
instal‐
la‐
tion,
default
(HP-
UX)
or
(Linux).
The license
terms.
Con‐
tains
the
license
terms
for
third-
party
soft‐
ware
used
by
exe‐
cutable.
Direc‐
tory
con‐
tain‐
ing
stan‐
dard
mea‐
sure‐
ment
con‐
fig‐
u‐
ra‐
tion
files.
Holds
use‐
ful
con‐
trib‐
uted
files.
Online
doc‐
u‐
men‐
ta‐
tion
direc‐
tory.
Exam‐
ple
files.
Con‐
tains
the
local
GUI
client
files.
Remote
GUI
client
instal‐
la‐
tion
files.
Con‐
tains
the
sys‐
tem_usage
dae‐
mon
exe‐
cutable
and
the
Ktracer/Ktrace‐
dump exe‐
cuta‐
bles.
Python
sup‐
port
direc‐
tory.
Man‐
page
direc‐
tory.
Shared
anal‐
y‐
sis
rules
direc‐
tory.
User
per‐
sonal
anal‐
y‐
sis
rules
direc‐
tory.
Implicit
data‐
bases
stor‐
age
direc‐
tory.
SEE
ALSO
aCC(1),
cc(1),
chatr(1),
f90(1),
ld(1).
Online
help
is
avail‐
able
at
(HTML
for‐
mat).
The
online
is
located
at
(PDF
ver‐
sion)
and
(HTML
ver‐
sion).
The
online
is
located
at
(PDF
ver‐
sion).
The
online
is
located
at
(PDF
ver‐
sion).
There
are
detailed
infor‐
ma‐
tion
files
describ‐
ing
each
HP
Caliper
mea‐
sure‐
ment
report
at
There
are
com‐
plete
lists
of
val‐
ues
with
full
descrip‐
tions
in
val‐
ues
(PMU
events)
are
also
described
in
the
doc‐
u‐
ment.
The
web‐
site
is
at
and
con‐
tains
addi‐
tional
tech‐
ni‐
cal
infor‐
ma‐
tion
and
updates.
Ref‐
er‐
ence
and
con‐
text-
sen‐
si‐
tive
help
for
the
HP
Caliper
GUI
is
avail‐
able
by
select‐
ing
the
"Help
Con‐
tents"
or
"Con‐
text-
sen‐
si‐
tive
Help"
items
in
the
"Help"
menu.
Integrity Systems Requires Optional HP Caliper Softwarecaliper(1)