caliper(1)

cpu execution statistics

sampled call stack profile

cache miss profiles

total cpu event counts

flat execution profile

sampled call graph profile

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.

Specifies a text file (OPTIONS_FILE) containing a list of caliper command-line options (separated by spaces or newlines). You can also use an options file to specify a caliper measurement configuration file as well as the application to be profiled and its arguments.

(Can also be specified with the -d option.)

This saves measurement results to the named database.

Performance data is always saved to a caliper database, whether one is explicitly specified or not. If the --database option is used to specify the explicit name and location of the database, then that database is used.

If the --database option is not given, then a 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.

The optional unique qualifier will append the process ID of the HP Caliper process to the name of the database it is writing to, e.g., mydb-21952.

Valid only for the dcache measurement, this option specifies that caliper should additionally record (and report) global variables and process regions (stack, heap, data, etc.) associated with data cache misses.

(Can also be specified with the -e option).

Specifies how long the measured application should run (in seconds) before caliper stops measuring it. When caliper 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:

[{privilege-level-mask|PLM}= ]{all|user|kernel } | {threshold|T}=THRESHOLD

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: user, kernel, and all.

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 cstack measurement, this option specifies the maximum number of frames to unwind while collecting call stack samples. The default depth is 32.

Specifies the default setting for load module inclusion in the measurement.

Specifies the load modules to be excluded from measurement. Module names can be given as a simple file name (libapplib1.so) which matches libraries of this name in any directory; a full-path file name (/home/dev/libs/libapplib1.so) which matches only this one specific library; or a full-path directory name (/usr/lib/) 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 (acount, cgprof, fcount, fcover), the specified load modules are not instrumented; for all other measurements, any samples 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 (libapplib1.so) which matches libraries of this name in any directory; a full-path file name (/home/dev/libs/libapplib1.so) which matches only this one specific library; or a full-path directory name (/usr/lib/) 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, Reporting Options.)

Defines a measurement's scope.

PSET_LIST is defined as: pset=pset_id [:pset_id]...

Caliper can measure activity on individual processes (process scope), on all CPUs in the system (system scope) or, on HP-UX systems, on all CPUs in selected processor sets (pset scope).

The system and pset scopes are supported for all PMU-based measurements (alat, branch, cpu, cycles, dcache dtlb, ecount, fprof, icache, itlb, pmu_ttrace, traps). The default scope is process.

With system and pset scopes, the qualifiers attr-mod, attr-proc, and attr-none can be specified. For measurements involving PMU samples, this determines how such samples are attributed. attr-mod is the default, and tells caliper to attribute samples to individual processes and their load modules, whenever possible.

attr-proc causes attribution simply to processes alone; attr-none 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 -w option is a shortcut for --scope=system,attr-mod.

When the scope is system, the command-line arguments program and program_args should not be provided. For more information, see System-Wide Measurements below.

Specifies how thread data should be collected and reported. Specify all to collect and report data per thread. (The -t option is a shortcut for --thread=all). Specify sum_all to collect and report data summed across threads. Default: sum_all.

Note that this option is currently only supported for the following measurements: alat, branch, cstack, cycles, dcache, dtlb, fprof, icache, itlb, traps.

Valid only for the cstack measurement, this option specifies a cutoff value that limits 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 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 call paths to be displayed (default: 5) regardless of the settings 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 all to report all source lines for reported functions. As with COUNT_SOURCE, set COUNT_DISASSEMBLY to show context disassembly lines (default: 3).

Applies to PMU histogram reports only.

Specifies a file in which to write a caliper performance report in Comma-Separated-Values format (CSV) for use in a spreadsheet or for further processing.

The file can be opened in append or create mode (default: create). Multi-process reports can be generated per-process (exec name is appended to each file) or to a single, shared file (default: shared). Specify unique to have the process ID appended to the report file name.

Target Application

Processor Information

Run Information

Target Execution Time

Sampling Specification

Load Modules Included

Report Help

Specifies a cutoff value that limits functions reported in function 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 functions to be displayed (default: 0) regardless of the settings for PERC_CUTOFF and CUM_PERC_CUTOFF.

Applies to PMU histogram reports only.

Specifies how data for matching processes and modules (those with matching basenames) is combined in reports.

Specify executable to have data for matching processes combined whenever possible. This is the default.

Specify module to ignore individual processes, and create a "module-centric" report for matching modules across all measured processes.

Specify none to combine no data across any processes.

Writes performance data as an HTML-formatted report in directory OUTPUT_DIR (default: ./Caliper_HTML).

STYLE specifies the color theme of the report. STYLE can be set to black, gold, or white (default: white).

ENTRIES_PER_PAGE specifies the number of entries on each web page (default: 20). The --html option is supported for the following reports: alat, branch, cgprof, cycles, dcache, dtlb, fprof, icache, itlb, scgprof, and traps.

Causes HP Caliper to append help information to the end of textual 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 kernel or all.

Specifies whether or not the latency bucket information should appear in dcachereports (default: TRUE).

This option is used only with the dcache measurement.

Specifies a list of directories to be searched when a load module 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 collection time.

(Can also be specified with the -o option.)

Specifies the file caliper writes its report to (default is stdout). The file can be opened in append or create mode (default: create).

Multi-process reports can be generated per-process (exec name is appended to each file) or to a single, shared file (default: shared).

Specify unique to have the process ID appended to the report file name.

Specifies whether or not caliper should report functions in one list (default: --per-module-data=FALSE), or report functions grouped by load module (--per-module-data=TRUE).

The following measurements support --per-module-data=TRUE: alat, branch, cycles, dcache, dtlb, fprof, icache, itlb, and traps.

Specifies what types of percentages are shown in reports.

Specify total to have a column showing percentage of samples with respect to total number of samples taken.

Specify cumulative 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 processes 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 caliper should look for and read .caliperinit, the caliper initialization file (default: TRUE).

Caliper looks for a .caliperinit file in the current directory; if not found, caliper 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 initialization file.

(Can also be specified with the -r option). For PMU histogram reports only. Specifies level of program detail reported (default: statement).

Specify statement to have data aggregated by source statement.

Specify instruction to obtain reports at the lowest level of granularity available.

Specify none to disable detail reports entirely. Specify all to print both source and instruction level details.

(Can also be specified with the -r option). For function coverage reports only. Specifies which coverage reports are produced.

Default: module:directory:file:function:unknown.

Specify module for the load module summary report, directory for the source directory summary report, file for the source file summary report, and/or function for the function detail report. Additionally specify unknown to include functions from unknown source files in the summary and detail coverage reports.

Valid only for cstack; 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 Metrics for Sorts/Cutoffs 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-separated 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 function 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 functions to be displayed (default: 5) regardless of the settings for PERC_CUTOFF and CUM_PERC_CUTOFF.

Applies to PMU histogram reports only.

Specifies the system model number for reporting latency buckets with the dcache 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 number using the model command (see model(1)).

Specifies which traps, faults, and interrupts (collectively referred to as traps) caliper 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 database 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:

For a list of all available values for TRAP_NAME, run the caliper command:

caliper info -r traps

Specifies which classes of advice to report (default: all). Every piece of advice is classified by which performance area it apples to.

Specify one or more of general for general advice, cpu for advice related to basic instruction execution, memory for memory-related information, io for input-output performance issues, and/or system 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 a list of files which contain the analysis rules to use (default: 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 (~/caliper_advisor), and finally (if still not found) in the directory of the running caliper (caliper_root/rules).

(Can also be specified with the -g 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 --jre is not specified, caliper will first check if the environment variable JAVA_HOME is set to a JRE; if not, caliper will attempt to find a JRE via the PATH environment variable.

(Can also be specified with the -c 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 --search option.

The information fields to output are given with the --report option. Use all to report on all cpu counters.

The --cpu-counter and --report options are mutually exclusive. If neither is given, then --cpu-counter is assumed.

(Can also be specified with the -d option.)

Specifies which information fields to include in cpu counter reports. It can be any combination of name, abbreviation, category, title, or description; separated by colons or all.

Default: name:abbreviation:title.

(Can also be specified with the -o option.)

Specifies the file in which to write the caliper information report (default is stdout).

The file can be opened in append or create mode (default: create).

(Can also be specified with the -r 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 measurement reports when the --info option is used.

Report types are alat, branch, dcache, dtlb, ecount, fprof, icache, itlb, pmu_trace, or scgprof.

Use all to report on all report types.

The --cpu-counter and --report options are mutually exclusive.

(Can also be specified with the -s option.)

Specifies which information fields are to be searched for cpu counter reports. It can be any combination of name, abbreviation, category, title, or description; separated by colons or all.

Default: name:abbreviation.

Prints the quick help text. When used, must be used alone on the caliper command line.

Prints the long help text. When used, must be used alone on the caliper command line.

Prints the caliper version identification. When used, must be used alone on the caliper command line.

Determines if targets of branch instructions are preceded by a colon (:) in disassembly.

Default: False

Specifies the maximum number of characters to print for branch target symbols in disassembly.

Default: 30

If TRUE, statement-level data in reports is placed in parentheses.

Default: True

If TRUE, no statement-level data will be reported.

Default: False

If TRUE, no warnings will be issued if unrecognized variables are detected in the initialization file or in measurement configuration files.

Default: False

.caliperinit in the current working directory

.caliperinit in your home directory.

The process is measured. Caliper is informed of new processes generated via fork, vfork, or exec.

The process is not measured. Caliper is informed of new processes generated via fork, vfork, or exec.

The process is not measured. Caliper is not informed of new processes generated via fork, vfork, or exec.

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 root for all measurements.

Each --process=some:... argument provided to Caliper is interpreted as an additional filter. Those filters are applied in order to each new process. If a filter matches the process, the behavior (measure, track, ignore) 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 OPT1,... component is provided, the default interpretation is as follows: the PATTERN component is interpreted as a list of glob 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 OPT1,... modifies those semantics as follow:

For keyword families measure|track|ignore, glob|regexp and file|arg0|arg1, only the last keyword used in each family is considered. For the keyword family root|fork|exec, multiple keywords will be considered as specifying a logical OR operation between the keywords.

The prefix some: is only necessary when no option is provided and the PATTERN could be mistaken for one of the simple options (root, root-forks, all, default).

Allows you to specify a Python function to be used as a filter for processes.

[sampled-misses]

target, branch-ways, [mispredict], back-end-only-mispredict

[samples], samples-running (HP-UX only), samples-blocked (HP-UX only)

[samples]

sampled-misses, [latency], avg-latency

[sampled-misses], l2-fills, hpw-fills, soft-fills

[samples]

sampled-misses, [latency], avg-latency

[sampled-misses], hpw-fills, soft-fills

[samples}, call-count, msecs-per-call

[samples]

By default, traps are always sorted on the first trap specified with --traps-reported (or ITLB if --traps-reported is not used). Specifying --sort-by=samples sorts based on values in the "Trap Samples" column.

specifies the databases directory where implicit caliper databases (those not specified with a --database option) are stored. The default databases directory is ./.hp_caliper_databases.

Specifies a set of caliper options which are used for every measurement run. The contents of CALIPER_OPTS is prepended to the command line before it is processed. It is possible to specify all caliper arguements and options via CALIPER_OPTS.

Measures basic block arc counts.

Measures call graph profile. (This is an enhanced version of the gprof command.)

Measures per-process metrics based on sampled CPU events.

Measures function counts.

Measures function coverage.

Specifies the bus speed in MHz for the sysbus event set. If you specify the sysbus event set, you must use the --bus-speed option to provide bus speed.

The --inlines option specifies that caliper should record and report inline functions, if data is available in the binary to discover such inlines.

This option is valid only when using the cpu measurement. Specifies how many samples (sampling period specified using --sampling-spec=TIME_PERIOD option) will be aggregated into one aggregated sample.

If COUNT is 0 or 1, the samples will not be aggregated. By default 125 low-level samples will be aggregated into one user-reported sample.

This option is valid only when using the cpu measurement. Specifies whether to print all 7 statistical metrics (statistics) or just the mean and standard deviation (means). samples controls the printing of each sample in addition to reporting the summary statistics.

The default is means (report only the mean and standard deviation values).

This option is not supported for cgprof, fcount, fcover, and acount runs.

The option is only valid when -w (--scope=system) is specified. This option is used to exclude/include the Caliper process activity as part of the measurement.

The default is TRUE (exclude).

Note that this option is not available on Linux and the behavior there is equivalent to a setting of FALSE (include Caliper).

The option is only valid when -w (--scope=system) is specified. This option is used to exclude/include the idle task as part of the measurement.

The default is TRUE (exclude).

Note that this option is not available on Linux and the behavior there is equivalent to a setting of FALSE (include the idle task).

This option is also supported for cgprof reports.

The default kernel path used is: /stand/current/vmunix (HP-UX 11i v2 and later).

This option controls whether the Itanium PMU is enabled while processing interrupts/traps.

The default is on for --scope=system and cpu measurements.

The default is off or the following measurements when the measurement scope is process (--scope=process): alat, branch, cycles, cache, dtlb, ecount, fprof, icache, itlb, pmu_trace, scgprof, traps.

Note that this option is not available on Linux and the behavior there is equivalent to a setting of on (PMU is enabled during regular processing as well as interrupt processing).

Controls the collection and reporting of memory usage data. Current memory use can be measured at any or all (all) of:

When making timed measurements, current memory use is sampled every PERIOD number of seconds (default if no qualifier is given), minutes, or hours.

Only samples which show a difference in memory utilization from the previous sample are saved and reported to reduce the volume of data. No memory usage data is collected or reported unless the option is used.

This measurement can be made in conjunction with any Caliper measurement. This option is only available on HP-UX 11i v2 or later and with --scope=process measurement runs.

Controls the type of data collected when you use the HP compilers' +Oprofile=collect option.

Choose arc-stride to collect arc counts, stride data, or both (depending on which have been enabled at compile time).

Choose dcache to collect data cache miss data.

Default: arc-stride.

Alternatively, you can choose the type of data collected by assigning arc-stride or dcache to the environment variable, PBO_DATA_TYPE.

This option also supports these report types: acount, cgprof, fcount, and fcover.

Controls the collection and reporting of system usage data. Two types of system usage data can be collected: runstatus (how much time each process spent running, eligible to run but not running, and waiting), syscalls (the count and time spent in every syscall called by a process), or all (the default).

No system usage data is collected or reported unless the option is used.

This measurement can be made in conjunction with any Caliper measurement. This option is only available on HP-UX 11i v2 or later and with --scope=process measurement runs.

For runs involving the Itanium PMU, specifies whether the data should be collected for the entire run (default), or only in regions delimited by the PMU enable/disable instructions (rum-sum). For more information, see Limiting PMU Measurements below.

Provides information on the dynamic mix of branch types, branch path distribution, branch per instruction, etc.

Provides metrics that are useful in assessing the effectiveness of branch prediction.

Provides metrics related to cache coherence activity.

Provides metrics related to Cycles Per Instruction (CPI)

Provides information on the demand that a specific CPU presents to the CEC chip set, and the demand the CPU experiences due to the CEC traffic initiated by other CPUs or I/O components in the system.

Provides metrics on the effectiveness of control speculation.

Provides qualitative view of the parallelism that is available as seen at instruction dispersal.

Provides metrics on the effectiveness of data speculation.

Provides miss rate information for the L1 data cache.

Provides miss and prefetch usage information for the L1 instruction cache.

Provides miss rate information for the L2 unified cache. Not available on dual-core processors.

Provides miss rate information for the L2 data cache. Only available on dual-core processors.

Provides miss rate information for the L2 instruction cache. Only available on dual-core processors.

Provides miss rate information for the L3 unified cache.

Provides an overview of processor activity by collecting multiple event sets.

On non-dual-core processors, the event sets used are: cpi, stall, dispersal, l1dcache, l1icache, l2cache, tlb, fp.

On dual-core processors, the event sets used are: cpi, stall, dispersal, l1dcache, l1icache, l2dcache, l2icache, tlb, fp, threadswitch.

Note that, on dual-core processors, specifying overview is equivalent to specifying:

--metrics=cpi,stall,dispersal,\

l1dcache,l1icache,l2dcache,l2icache,\

l2dcache,l2icache,tlb,fp,threadswitch

Provide BRQ (Bus Request Queue) metrics that may give some insight into possible system bus related performance problems.

Provides metrics on primary CPU performance limiters by breaking the CPI into seven components.

Provides metrics on system bus utilization. If you specify the sysbus event set, you must use the --bus-speed option to provide bus speed in MHz. For example, --bus-speed=200.

Provides metrics related to TLB misses.

Provides metrics on hyperthreading thread switch behavior. Only available on dual-core processors.

arc-count, [taken-count]

[samples], seconds, call-count, msecs-per-call

[call-count]

address, name, reached-count, reached-percent, unreached-count, [unreached-percent]

Specifies the (non-default) caliper_root location when caliper is automatically invoked.

This is only needed when caliper is not installed in its default location (/opt/caliper) and a program compiled with the +Oprofile=collect option (profile based optimization) is run.