HP HP Caliper User Manual

HP Caliper User Guide

Release 5.7

HP Part Number: 769153-001 Published: March 2014 Edition: 5.7

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

UNIX is a registered trademark of The Open Group.

Intel® and Itanium® are registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

HP secure development lifecycle....................................................................12

About This Document...................................................................................13

1 HP Caliper at a Glance............................................................................17

What is HP Caliper?...............................................................................................................17

What Does HP Caliper Run On?..............................................................................................19

Supported Hardware and Operating Systems........................................................................19

Supported Compilers and Application Environments...............................................................19

Summary of HP Caliper Features..............................................................................................20

2 Getting Started with the HP Caliper Command-Line Interface..........................21

Example: Running fprof on a Short Program, with Default Output..................................................21

Example: Adding Instructions to an fprof Report..........................................................................25

Types of Measurements...........................................................................................................27

Global Measurement..........................................................................................................27

Sampled Measurements......................................................................................................27

Precise Measurements (HP-UX only) .........................................................................27

What to Look for in Using HP Caliper.......................................................................................28

Syntax for caliper Command....................................................................................................28

Basic Tasks: A Quick Reference................................................................................................29

Starting HP Caliper............................................................................................................29

Stopping HP Caliper..........................................................................................................29

Showing HP Caliper Options...............................................................................................29

Creating a Call Graph Profile with HP Caliper.......................................................................29

Creating a Text Report for Analysis.......................................................................................30

Creating a Report Based on Your Collected Data...................................................................30

Using the HP Caliper Advisor...................................................................................................30

Restrictions on Using HP Caliper...............................................................................................30

Additional HP Caliper Commands............................................................................................31

Getting Information About HP Caliper.......................................................................................31

3 Getting Started with the HP Caliper GUI......................................................32

What Is the HP Caliper GUI?...................................................................................................32

Window Basics......................................................................................................................32

Projects View .................................................................................................................33

Collect View ..................................................................................................................34

Analyze View ................................................................................................................35

Advisor View .................................................................................................................36

Console View ................................................................................................................37

Diagnostics View ...........................................................................................................38

Help View .....................................................................................................................38

Tips for Using Views...........................................................................................................39

Making Measurements............................................................................................................39

Hints on How to Make Measurements...................................................................................39

Exploring Performance Data.....................................................................................................40

Getting Performance Tuning Advice...........................................................................................40

Getting Help..........................................................................................................................41

Starting the GUI.....................................................................................................................41

Native (Local) GUI.............................................................................................................41

Remote GUI......................................................................................................................41

Contents 3

4 HP Caliper Measurement Configuration Files................................................43

Measurement Configuration Files Provided with HP Caliper..........................................................43

Overview Measurement...........................................................................................................45

Simultaneous fprof Sampling on Multiple PMU Counters..............................................................46

Location of Measurement Configuration Files..............................................................................46

Specifying Option Values in Measurement Configuration Files..................................................46

Using the Command Line to Override Measurement Configuration File Parameters......................47

5 HP Caliper Options..................................................................................48

Basic Information About Options..............................................................................................48

Multiple Ways to Specify HP Caliper Option Values...............................................................48

Hierarchy for Processing an Option Value.............................................................................49

-d or --database......................................................................................................................49

-e or --duration........................................................................................................................49

-f or --options-file.....................................................................................................................50

-h or -?..................................................................................................................................50

-H or --help.............................................................................................................................50

-m or --metrics.........................................................................................................................50

-m cpu_event.....................................................................................................................50

-m event_set (HP-UX only) .......................................................................................51

-o or --output-file......................................................................................................................51

-p or --process.........................................................................................................................52

-r or --report-details..................................................................................................................52

-r for PMU Histogram Reports..............................................................................................52

-r for Function Coverage Reports..........................................................................................52

-s or --sampling-spec................................................................................................................53

-v or --version..........................................................................................................................54

-w.........................................................................................................................................54

--advice-classes.......................................................................................................................54

--advice-cutoff.........................................................................................................................55

--advice-details.......................................................................................................................55

--analysis-focus........................................................................................................................55

--branch-sampling-spec............................................................................................................55

--bus-speed (HP-UX only) ....................................................................................................56

--callpath-cutoff ......................................................................................................................56

--context-lines..........................................................................................................................57

--cpu-aggregation (HP-UX only) ....................................................................................57

--cpu-counter..........................................................................................................................57

--cpu-details(HP-UX only) .............................................................................................57

--csv-file.................................................................................................................................57

Examples..........................................................................................................................58

--dcache-data-profile................................................................................................................58

--database.............................................................................................................................58

--dcache-hits ..........................................................................................................................58

--dcache-stores .......................................................................................................................58

--dbrp....................................................................................................................................58

--db-save................................................................................................................................59

--debug-file-path=....................................................................................................................59

--description-details ................................................................................................................59

--details.................................................................................................................................59

--detail-cutoff...........................................................................................................................59

Example...........................................................................................................................60

--duration...............................................................................................................................60

--etb-freeze-delay....................................................................................................................60

Example...........................................................................................................................61

4 Contents

--etb-walkback-cycles...............................................................................................................61

--event-defaults........................................................................................................................61

Example...........................................................................................................................62

--exclude-caliper (HP-UX only) ......................................................................................62

--exclude-idle (HP-UX only) ..........................................................................................62

--fold.....................................................................................................................................62

--frame-depth..........................................................................................................................62

--group-by..............................................................................................................................62

--help....................................................................................................................................63

--hotpaths...............................................................................................................................63

--ibrp.....................................................................................................................................63

--info.....................................................................................................................................64

--inlines (HP-UX only) ..................................................................................................64

--join.....................................................................................................................................64

--jre ......................................................................................................................................64

--kernel-path...........................................................................................................................64

--kernel-stack (HP-UX only) ...........................................................................................65

--latency-buckets......................................................................................................................65

--measure-on-interrupts (HP-UX only) .............................................................................65

--memory-usage=(HP-UX only) ......................................................................................65

--metrics.................................................................................................................................66

--module-default......................................................................................................................66

--module-exclude.....................................................................................................................66

--module-include.....................................................................................................................66

--module-search-path...............................................................................................................67

--noinlines..............................................................................................................................67

--omr.....................................................................................................................................67

--options-file............................................................................................................................68

--output-file.............................................................................................................................68

--overflow-block.......................................................................................................................68

--per-module-data....................................................................................................................68

--percent-columns....................................................................................................................68

--percent-sample......................................................................................................................68

--prim-cutoff............................................................................................................................68

--process................................................................................................................................69

--process-cutoff........................................................................................................................69

Example...........................................................................................................................70

--read-init-file..........................................................................................................................70

--report..................................................................................................................................70

--report-details........................................................................................................................70

--rule-files...............................................................................................................................70

--sampling-spec.......................................................................................................................70

--scope..................................................................................................................................70

Using --scope system for System-Wide Measurements..............................................................71

Limitations in Using --scope system...................................................................................72

--search.................................................................................................................................72

--skip-functions .......................................................................................................................72

--sort-by.................................................................................................................................72

--source-path-map....................................................................................................................73

--stop-functions(HP-UX only) ................................................................................................73

--summary-cutoff......................................................................................................................73

--sw-process-list=.....................................................................................................................74

--system-model (Linux only)........................................................................................................74

--system-usage=(HP-UX only) ........................................................................................74

--term-display..........................................................................................................................75

Contents 5

--threads................................................................................................................................75

--traps-reported.......................................................................................................................75

--user-regions (HP-UX only) .................................................................................................76

--version.................................................................................................................................76

6 Using the HP Caliper Advisor.....................................................................77

What Is the HP Caliper Advisor?..............................................................................................77

Example of an HP Caliper Advisor Report..................................................................................77

Steps in Using the Advisor.......................................................................................................78

Command Line to Invoke the Advisor.........................................................................................79

Getting Started with the Advisor: Examples................................................................................81

Simplest Example...............................................................................................................81

More Typical Examples.......................................................................................................81

Explanation of Report Output..............................................................................................82

How to Read an Advisor Report................................................................................................83

Suggestions for Using the HP Caliper Advisor.............................................................................84

How the HP Caliper Advisor Works..........................................................................................85

7 Using the HP Caliper Advisor in the GUI.....................................................86

Basic Steps in Using the HP Caliper Advisor in the GUI...............................................................86

Making Performance Measurement Runs....................................................................................86

Selecting Performance Data to Analyze [Optional] .....................................................................87

Generating Advice.................................................................................................................89

Reviewing and Acting on the Advice.........................................................................................90

8 Configuring HP Caliper ............................................................................92

Specifying Option Values with a .caliperinit Initialization File........................................................92

Example of a .caliperinit File...............................................................................................92

Setting Constants in the .caliperinit File.................................................................................93

Configuring Data Collection.....................................................................................................94

Specifying Which CPU Events to Measure.............................................................................94

Shortening CPU Event Names.........................................................................................94

Specifying Which Load Modules to Collect Data For..............................................................95

Default Settings for Load Module Data Collection..............................................................95

How to Specify Load Module Names...............................................................................96

Controlling Granularity of Data Collection and Reports...........................................................97

Specifying Processes to Measure..........................................................................................97

Process Tree Report.......................................................................................................97

Syntax for -p Option......................................................................................................98

Using -p some ..............................................................................................................99

Examples of the -p Option ...........................................................................................100

Using HP Caliper in Your Build Process...............................................................................100

Using HP Caliper in Testing and Quality Assurance.........................................................100

Using HP Caliper to Generate Test Suite Reports.............................................................101

Attaching to a Running Process to Perform Measurements......................................................101

How to Display Reference Information About CPU Counters or HP Caliper Report Types.................102

Options for the caliper info Command................................................................................102

-c or --cpu-counter........................................................................................................102

-d or --details..............................................................................................................103

-o or --output-file..........................................................................................................103

-r or --report................................................................................................................103

-s or --search...............................................................................................................103

Examples of the caliper info Command...............................................................................103

HP Caliper Environment Variables...........................................................................................104

9 Controlling the Content of Reports.............................................................105

Layout of an HP Caliper Text or CSV Report.............................................................................105

6 Contents

Metrics You Can Use for Report Sorting and Cutoffs..................................................................106

Module-Centric Reports.........................................................................................................109

Process Summary.................................................................................................................110

Function Details....................................................................................................................111

Disassembly Listing...............................................................................................................111

Branch Targets in Disassembly Listings................................................................................112

Source Position Correlation....................................................................................................112

Source Line Data.............................................................................................................112

Address Types Shown............................................................................................................112

How Functions Are Named in Reports.....................................................................................113

Unnamed Functions..........................................................................................................113

Unknown Functions..........................................................................................................113

VSE Information Shown in Report Output (HP-UX only) ..................................................113

HyperThreading Information for Dual-Core Itanium 2 and Itanium 9300 Quad-Core Processors Shown

in Report Output...................................................................................................................114

How HP Caliper Saves Data in Databases...............................................................................115

Names and Locations for the Databases.............................................................................115

Changing the Default Name and Location......................................................................115

Creating Reports from Multiple Databases...............................................................................116

Using the caliper report Command to Create a Report from One or More Databases................117

Using the caliper merge Command to Merge Data From Multiple Collection Runs....................117

Using the caliper diff Command to Difference Data Collected in Two Databases......................119

Example of How to Use the caliper diff Command...........................................................121

10 Producing a Sampled Call Graph Profile Analysis.....................................122

How Sampled Call Graph Profile Analysis Works.....................................................................122

Differences Between scgprof and cgprof..................................................................................122

Running the HP Caliper Sampled Call Graph Profile..................................................................123

Sampled Call Graph Text Report Example ...............................................................................123

Sampled Call Graph Profile Report Details...............................................................................132

Flat Profile Part of the Report..............................................................................................132

Call Graph Part of the Report............................................................................................132

Hot Call Paths Part of the Report........................................................................................132

Function Indexes..............................................................................................................132

Diagnostic Messages........................................................................................................133

gprof Fallacy and Possibly Misleading Results...........................................................................133

11 Producing a Sampled Call Stack Profile Analysis.......................................134

Running HP Caliper to Produce a Call Stack Profile...................................................................134

Call Stack Profile Text Report Example for HP-UX.......................................................................134

Call Stack Profile Text Report Example for Linux........................................................................142

Call Stack Profile Report Details..............................................................................................149

Flat Profile Part of the Report..............................................................................................149

Blocking Primitives Summary Part of the Report....................................................................149

Thread Synchronization Primitive's Holder and Waiter Thread Analysis (HP-UX 11.31 only)....149

Hot Call Paths Part of the Report........................................................................................150

Call Graph Part of the Report............................................................................................151

Function Indexes..............................................................................................................151

Avoids gprof Fallacy.............................................................................................................151

Limitations to Using cstack.....................................................................................................151

Pstack like functionality..........................................................................................................151

12 Performing CPU Metrics Analysis (HP-UX only) ................................153

13 HP Caliper Features Specific to HP-UX (HP-UX only) .........................154

Measuring Memory Usage Concurrently with Other Measurements (HP-UX only) ....................154

Examples of the --memory-usage= Option............................................................................155

Contents 7

Example Report Output.....................................................................................................156

How to Read the Reports..................................................................................................156

System Memory Configuration Table..............................................................................156

Process Memory Usage Table.......................................................................................157

Measuring System Usage Concurrently with Other Measurements (HP-UX only) .......................158

Example Report Output.....................................................................................................158

Interpreting the Data........................................................................................................160

Attaching to a Running Process to Perform Precise Measurements (HP-UX only) .......................160

Taking PMU Samples in Your Code (HP-UX only) .........................................................161

Triggering PMU Samples in Specific Code Regions...............................................................161

Precautions When Using Triggered Samples...................................................................162

Restricting PMU Measurements to Specific Code Regions.......................................................163

14 Documentation feedback.......................................................................166

A HP Caliper Diagnostic and Warning Messages..........................................167

ERROR #28: Caliper Invalid Measurement Combination............................................................167

Instructions Labeled STUB.......................................................................................................167

Mispredicted Branches..........................................................................................................167

PMU Sample Hits Outside Function Range...............................................................................169

scgprof Reports Require Kernel Patch (HP-UX only) ..............................................................169

B Descriptions of Measurement Reports........................................................171

alat Measurement Report Description......................................................................................171

Example Command Line for Text Report..............................................................................171

Example Command Line for CSV Report..............................................................................171

alat Metrics Summed for Entire Run....................................................................................171

Metrics for Integrity Servers Itanium 2 Systems.................................................................172

Metrics for Integrity Servers Dual-Core Itanium 2 and Itanium 9300 Quad-Core Processor

Systems......................................................................................................................172

Metrics for Integrity Servers Intel® Itanium® 9500 Processors Systems ...............................173

alat Measurement Report Metrics.......................................................................................174

How ALAT Metrics Are Obtained.......................................................................................175

branch Measurement Report Description..................................................................................175

Example Command Line for Text Report..............................................................................175

Example Command Line for CSV Report..............................................................................175

branch Metrics Summed for Entire Run................................................................................175

Metrics for Integrity Servers Itanium 2 Systems.................................................................175

Metrics for Integrity Servers Dual-Core Itanium 2 and Itanium 9300 Quad-Core Processor

Systems......................................................................................................................176

Metrics for Integrity Servers Intel® Itanium® 9500 Processors Systems ...............................177

branch Measurement Report Metrics...................................................................................179

How branch Metrics Are Obtained.....................................................................................180

cgprof Report Description (HP-UX only) .......................................................................180

Example Command Line for Text Report..............................................................................180

Example Command Line for CSV Report..............................................................................180

HP Caliper Call Graph Profile Results Accuracy...................................................................180

Call Graph Profile Metrics.................................................................................................181

cpu Measurement Report Description (HP-UX only) .......................................................183

Example Command Lines for Text Report.............................................................................184

Example Command Line for CSV Report..............................................................................184

CPU Event Sets................................................................................................................184

cstack Measurement Report Description...................................................................................186

Example Command Line for Text Report..............................................................................186

Example Command Line for CSV Report..............................................................................186

cstack Measurement Report Metrics....................................................................................186

8 Contents

cycles Measurement Report Description ..................................................................................188

Example Command Line for Text Report..............................................................................189

Example Command Line for CSV Report..............................................................................189

cycles Metrics Summed for Entire Run.................................................................................189

Metrics for Integrity Servers Intel Itanium 9300 processors Systems and older......................189

Metrics for Integrity Servers Intel® Itanium® 9500 Processors Systems ...............................190

cycles Measurement Metrics..............................................................................................192

How cycles Metrics Are Obtained......................................................................................192

dcache Measurement Report Description.................................................................................193

Example Command Line for Text Report..............................................................................193

Example Command Line for CSV Report..............................................................................193

dcache Metrics Summed for Entire Run...............................................................................194

Metrics for Integrity Servers Itanium 2 Systems ................................................................194

Metrics for Integrity Servers Dual-Core Itanium 2 and Itanium 9300 Quad-Core Processor

Systems......................................................................................................................194

Metrics for Integrity Servers Intel® Itanium® 9500 Processors Systems ...............................195

dcache Measurement Report Metrics..................................................................................196

Example dcache Reports...................................................................................................198

Using the --dcache-data-profile Option to Produce a Data Summary........................................199

Using the --dcache-stores Option to Produce a Data Cache Store Profile .................................200

How Data Cache Metrics Are Obtained.............................................................................200

How Latency Bucket Metrics Are Obtained.....................................................................201

How the Data Summary Information Is Obtained.............................................................201

dtlb Measurement Report Description......................................................................................201

Example Command Line for Text Report..............................................................................201

Example Command Line for CSV Report..............................................................................201

dtlb Metrics Summed for Entire Run....................................................................................202

Metrics for Integrity Servers Itanium 2 Systems.................................................................202

Metrics for Integrity Servers Dual-Core Itanium 2 and Itanium 9300 Quad-Core Processor

Systems......................................................................................................................202

Metrics for Integrity Servers Intel® Itanium® 9500 Processors Systems ...............................203

dtlb Measurement Report Metrics.......................................................................................204

How Data TLB Metrics Are Obtained..................................................................................205

ecount Measurement Report Description..................................................................................206

Example Command Line for Text Report..............................................................................206

Example Command Line for CSV Report..............................................................................206

ecount Metrics Summed for Entire Run................................................................................206

Metrics for Integrity Servers Itanium 2 Systems.................................................................206

Metrics for Integrity Servers Dual-Core Itanium 2 and Itanium 9300 Quad-Core Processor

Systems......................................................................................................................206

Metrics for Integrity Servers Intel® Itanium® 9500 Processors Systems................................207

fcount Measurement Report Description (HP-UX only) ....................................................208

Example Command Line for Text Report..............................................................................209

Example Command Line for CSV Report..............................................................................209

fcount Measurement Report Metrics....................................................................................209

fcover Measurement Report Description (HP-UX only) ....................................................209

Example Command Line for Text Report..............................................................................209

Example Command Line for CSV Report..............................................................................209

fcover Measurement Report Metrics....................................................................................209

Unknown Source Files.......................................................................................................210

-r for Function Coverage Reports........................................................................................210

fprof Measurement Report Description.....................................................................................210

Example Command Line for Text Report..............................................................................210

Example Command Line for CSV Report..............................................................................211

fprof Metrics Summed for Entire Run...................................................................................211

Contents 9

Metrics for Integrity Servers Itanium 2 Systems.................................................................211

Metrics for Integrity Servers Dual-Core Itanium 2 and Itanium 9300 Quad-Core Processor

Systems......................................................................................................................211

Metrics for Integrity Servers Intel® Itanium® 9500 Processors Systems ...............................212

fprof Measurement Metrics................................................................................................213

How fprof Metrics Are Obtained........................................................................................214

icache Measurement Report Description...................................................................................215

Example Command Line for Text Report..............................................................................215

Example Command Line for CSV Report..............................................................................215

icache Metrics Summed for Entire Run................................................................................215

Metrics for Integrity Servers Itanium 2 Systems.................................................................215

Metrics for Integrity Servers Dual-Core Itanium 2 and Itanium 9300 Quad-Core Processor

Systems......................................................................................................................216

Metrics for Integrity Servers Intel® Itanium® 9500 Processors Systems ...............................217

icache Measurement Report Metrics...................................................................................218

Function Details...............................................................................................................219

How Instruction Cache Metrics Are Obtained......................................................................219

itlb Measurement Report Description.......................................................................................219

Example Command Line for Text Report..............................................................................220

Example Command Line for CSV Report..............................................................................220

itlb Metrics Summed for Entire Run.....................................................................................220

Metrics for Integrity Servers Itanium 2 Systems.................................................................220

Metrics for Integrity Servers Dual-Core Itanium 2 and Itanium 9300 Quad-Core Processor

Systems......................................................................................................................220

Metrics for Integrity Servers Dual-Core Intel® Itanium® 9500 Processors Systems ................221

itlb Measurement Report Metrics........................................................................................222

Function Details...............................................................................................................223

How Instruction TLB Metrics Are Obtained...........................................................................223

pmu_trace Measurement Report Description.............................................................................224

Example Command Line for Text Report..............................................................................224

Example Command Line for CSV Report..............................................................................224

scgprof Measurement Report Description.................................................................................224

Example Command Line for Text Report..............................................................................224

Example Command Line for CSV Report..............................................................................224

scgprof Measurement Report Metrics (Flat Profile).................................................................224

scgprof Measurement Report Metrics (Call Graph Profile)......................................................225

traps Measurement Report Description ....................................................................................227

Example Command Line for Text Report..............................................................................228

Example Command Line for CSV Report..............................................................................228

traps Metrics Summed for Entire Run...................................................................................228

traps Measurement Metrics................................................................................................230

How traps Metrics Are Obtained ......................................................................................231

C Event Set Descriptions for CPU Metrics (HP-UX only) .........................232

brpath Event Set...................................................................................................................232

Metrics Available from this Measurement............................................................................232

brpred Event Set...................................................................................................................233

Metrics Available from this Measurement............................................................................233

c2c Event Set.......................................................................................................................235

Metrics Available from this Measurement............................................................................235

cpi Event Set........................................................................................................................236

Metrics Available from this Measurement............................................................................237

cpubus Event Set..................................................................................................................238

Metrics Available from this Measurement............................................................................238

cspec Event Set....................................................................................................................239

10 Contents

Metrics Available from this Measurement............................................................................239

dispersal Event Set................................................................................................................240

Metrics Available from this Measurement............................................................................240

dspec Event Set....................................................................................................................241

Metrics Available from this Measurement............................................................................242

fp Event Set..........................................................................................................................243

Correspondence Between Floating-Point Instructions and Operations.......................................243

Metrics Available from this Measurement............................................................................244

l1dcache Event Set...............................................................................................................245

Metrics Available from this Measurement............................................................................245

l1icache Event Set................................................................................................................246

Metrics Available from this Measurement............................................................................247

l2cache Event Set.................................................................................................................248

Metrics Available from this Measurement............................................................................248

l2dcache Event Set...............................................................................................................250

Metrics Available from this Measurement............................................................................250

l2icache Event Set................................................................................................................251

Metrics Available from this Measurement............................................................................252

l3cache Event Set.................................................................................................................253

Metrics Available from this Measurement............................................................................253

Metrics Available for Intel Itanium 2 and dual core Itanium 2 processor systems..................253

Metrics Available for Intel® Itanium® 9500 series systems ...............................................255

memreq Event Set.................................................................................................................255

Metrics Available from this Measurement............................................................................255

queues Event Set..................................................................................................................256

Metrics Available from this Measurement............................................................................257

snoop Event Set....................................................................................................................258

Metrics Available from this Measurement............................................................................258

Metrics Available for Intel Itanium 2 and dual core Itanium 2 processor systems..................258

replay Event Set....................................................................................................................259

Metrics Available from this Measurement ...........................................................................259

stall Event Set.......................................................................................................................259

Metrics Available for Intel Itanium 2 and dual core Itanium 2 processor systems.......................260

Metrics Available for Intel® Itanium® 9500 series systems ....................................................261

sysbus Event Set...................................................................................................................261

Metrics Available from this Measurement............................................................................262

threadswitch Event Set...........................................................................................................263

Metrics Available for Intel Itanium 2 and dual core Itanium 2 processor systems.......................264

Metrics Available for Intel® Itanium® 9500 series systems ....................................................265

tlb Event Set.........................................................................................................................266

Metrics Available from this Measurement............................................................................266

Glossary..................................................................................................268

Index.......................................................................................................273

Contents 11

HP secure development lifecycle

Starting with HP-UX 11i v3 March 2013 update release, HP secure development lifecycle provides the ability to authenticate HP-UX software. Software delivered through this release has been digitally signed using HP's private key. You can now verify the authenticity of the software before installing the products, delivered through this release.

To verify the software signatures in signed depot, the following products must be installed on your system:

• B.11.31.1303 or later version of SD (Software Distributor)

• A.01.01.07 or later version of HP-UX Whitelisting (WhiteListInf)

To verify the signatures, run: /usr/sbin/swsign -v –s <depot_path>. For more information, see Software Distributor documentation at http://www.hp.com/go/sd-docs.

NOTE: Ignite-UX software delivered with HP-UX 11i v3 March 2014 release or later supports

verification of the software signatures in signed depot or media, during cold installation. For more information, see Ignite-UX documentation at http://www.hp.com/go/ignite-ux-docs.

About This Document

This document describes how to use HP Caliper to measure the performance of native applications running on HP-UX and Linux Integrity servers.

NOTE: For the latest version of this document, go to the HP Caliper Web site at the following

URL and click on Documentation in the Product Information box:

http://hp.com/go/caliper

This document is sometimes updated after a release. The document publication date appears on the title page.

Intended Audience

This document is written for software developers who want to improve the performance of their application programs. It assumes that you are familiar with compilers and with performance analysis concepts. It is not necessary for you to have used a performance analysis tool before to use HP Caliper.

New and Changed Information in This Edition

New Information

The HP Caliper 5.7 release has the following improvements:

• Improved accuracy in some of the CPU metrics measurement for Intel® 9500 processors.

• Quality improvements and defect fixes.

Deprecated Options

None

Deleted Information

None.

Document Organization

For information to help you get started, read these chapters:

• “HP Caliper at a Glance” (p. 17) provides an introduction to HP Caliper.

• “Getting Started with the HP Caliper Command-Line Interface” (p. 21) helps you get started

using the HP Caliper command-line interface.

• “Getting Started with the HP Caliper GUI” (p. 32) introduces you to the HP Caliper graphical

user interface (GUI).

For more advanced information, read these chapters:

• “HP Caliper Measurement Configuration Files” (p. 43) describes the measurement configuration

files provided with HP Caliper.

• “HP Caliper Options” (p. 48) describes the HP Caliper options in alphabetical order.

For information about the HP Caliper Advisor, read this chapter:

• “Using the HP Caliper Advisor” (p. 77).

For information about how to configure HP Caliper to collect data and report the results, read these chapters:

• “Configuring HP Caliper ” (p. 92) describes how you can configure HP Caliper to collect

data.

• “Controlling the Content of Reports” (p. 105) describes how to control the content of reports

based on the data collected.

For information about how to run particular measurements, read these chapters:

• “Producing a Sampled Call Graph Profile Analysis” (p. 122) describes how to use HP Caliper

to produce a sampled call graph profile analysis.

• “Producing a Sampled Call Stack Profile Analysis” (p. 134) describes how to use HP Caliper

to produce a sampled call stack profile analysis.

• “Performing CPU Metrics Analysis ” (p. 153) describes how to measure CPU metrics on

HP-UX.

For information about HP Caliper features specific to HP-UX, read this chapter:

• “HP Caliper Features Specific to HP-UX ” (p. 154).

Also see these appendixes:

• “HP Caliper Diagnostic and Warning Messages” (p. 167) describes some diagnostic and

warning messages you might receive.

• “Descriptions of Measurement Reports” (p. 171) provides descriptions of reports produced for

all of the HP Caliper measurements.

• “Event Set Descriptions for CPU Metrics ” (p. 232) contains descriptions for the output of

each event set available with the cpu measurement.

Typographic Conventions

This document uses the following typographic conventions: $ The system prompt for the Bourne, Korn, and POSIX shells.

audit(5) A manpage. The manpage name is audit, and it is located in

Section 5.

Command A command name or qualified command phrase. Computer output Text displayed by the computer.

Ctrl+x A key sequence. A sequence such as Ctrl+x indicates that you

must hold down the key labeled Ctrl while you press another key

or mouse button. ENVIRONMENT VARIABLE The name of an environment variable, for example, PATH. ERROR NAME The name of an error, usually returned in the errno variable. File name The name of a file, a measurement, or an event set. Key The name of a keyboard key. Return and Enter both refer to the

same key. Term The defined use of an important word or phrase. User input Commands and other text that you type.

Variable The name of a placeholder in a command, function, or other

syntax display that you replace with an actual value. An example

is program, where the actual file name will vary.

GUI item A graphical user interface (GUI) item such as a button or menu

name.

[] The contents are optional in syntax. If the contents are a list

separated by |, you must choose one of the items.

{} The contents are required in syntax. If the contents are a list

separated by |, you must choose one of the items.

... The preceding element can be repeated an arbitrary number of

times.

| Separates items in a list of choices.

1 HP Caliper at a Glance

What is HP Caliper?

HP Caliper is a general-purpose performance analysis tool for applications on HP-UX and Linux systems running on HP Integrity Servers. HP Caliper allows you to understand the performance and execution of your application and to identify ways to improve its run-time performance.

HP Caliper works with any native Integrity Server application. It does not require special compilation of the program being analyzed and does not require any special link options or libraries. HP Caliper supports programs compiled with any compiler option.

HP Caliper provides ways to:

• Measure the overall performance of a program

• Identify performance parameters of specific functions in a program

• Guide you in optimizing the performance of a program based on its specific execution profile

HP Caliper has two user interfaces:

• Graphical user interface (GUI)

• Command-line interface (CLI)

These two interfaces are part of the same product. You can mix-and-match your use of the GUI and the command line.

The GUI can run either natively (locally) on the HP-UX or Linux Integrity server that HP Caliper is running on, or remotely on a Windows x86 or Linux x86 desktop system.

HP Caliper operates in these modes:

• Data collection

• Report generation

• Performance analysis

The data collection output is saved automatically in a database for possible use later. Report generation can be done in the data collection run or in separate report generation runs later.

The output data is delivered in multiple report formats, with source and assembly code, and explanatory help text.

Figure 1 shows the HP Caliper components.

What is HP Caliper? 17

Figure 1 HP Caliper Components (User Interfaces)

HP Caliper CLI

Performance

reports

HP Caliper

database(s)

Integrity Server (HP-UX or Linux)

X86 desktop (Windows or Linux)

Application

HP Caliper

HP Caliper GUI

(local)

HP Caliper GUI

(remote)

X11

server

HP Caliper selectively measures the processes, threads, and load modules of your application. HP Caliper performs data collection in one of two modes:

• System-wide: In a system-wide measurement, HP Caliper measures activity across the entire

system, and attributes measurements to the kernel and individual processes where possible.

• Per-process: In a per-process measurement, HP Caliper tracks individual processes and their

children and measures each separately.

HP Caliper uses the performance monitoring unit (PMU) of the Itanium processor family to gather the requested performance data. This is done primarily through non-intrusive sampling, both time-based and event-based, as well as exact counts of particular metrics. HP Caliper provides data on hundreds of events monitored by the PMU.

On HP-UX, it also uses dynamic instrumentation of code for some measurements. It only instruments the portions of the application that actually get executed, thus eliminating unnecessary instrumentation overhead.

Reports show measured data by thread, load module, function, statement, and instruction. HP Caliper uses a single command (called caliper) for all measurements. You specify the type

of measurement and the target program as command-line arguments. For example:

$ caliper myprog

This command uses a default measurement called scgprof to produce a sampled call graph profile of the program myprog. The result of the measurement (the output) is saved automatically in a database. The output database is called scgprof and is placed in a databases directory in your current directory unless you specify otherwise.

By default, a text report describing the results of the measurement run is sent to stdout. Using the HP Caliper GUI, you have access to all of HP Caliper's features and options using intuitive

menus and buttons. HP Caliper has many types of preconfigured measurements that can be performed on a program.

For example, there are measurements to determine cache misses, stalls, and call graphs. You can further customize your measurements by using HP Caliper options as parameters to the caliper command.

18 HP Caliper at a Glance

In general, HP Caliper runs do one of the following:

• Collect data

• Collect data and generate a report

• Generate a report based on previously collected data

• Analyze previously collected data

For the last item above, HP Caliper provides the HP Caliper Advisor, a rules-based expert system designed to provide guidance about improving the performance of an application. Users can write their own rules to analyze applications or use the default rules provided.

The latest version of HP Caliper is available on the HP Caliper home page at:

http://hp.com/go/caliper

What Does HP Caliper Run On?

Supported Hardware and Operating Systems

HP Caliper is supported on HP Integrity systems. HP Caliper does not measure programs compiled for PA-RISC processors.

HP Caliper is supported on these operating systems:

• HP-UX 11i v2 or later

• Linux version 2.6: RedHat4, Debian 3.0, and SuSE Enterprise Linux 9

HP Caliper can be used in an Integrity Virtual Machine environment on a guest system.

Supported Compilers and Application Environments

On HP-UX, HP Caliper is formally supported for HP C/aC++ and HP Fortran. (These are also the compilers it is bundled with.) HP Caliper measures code generated by these native and cross compilers, including inlined functions and C++ exceptions. Instrumentation-based measurements will only work on applications compiled on these compilers.

On Linux, HP Caliper has been primarily validated with code produced with gcc and g++, and minimally tested with code produced from the Intel icc compiler.

HP Caliper can generally be used on:

• Programs compiled using HP, Intel, and GNU compilers, with and without optimization.

• Assembly and Java programs.

• Stripped programs, and programs compiled with optimization or debug information or both.

This includes support for both the +objdebug and +noobjdebug options.

• Both ILP32 (+DD32) and LP64 (+DD64) programs, both 32-bit and 64-bit ELF formats.

• Archive-, minshared- or shared-bound executables.

• Single-process and multiprocess applications.

• Single-threaded and multithreaded applications, including MxN threads.

• Applications that fork or vfork or exec themselves or other executables.

• Shell scripts and the programs they spawn.

• Main, static, and dynamic shared libraries.

• Entire run, partial run, and server/daemon programs.

What Does HP Caliper Run On? 19

Summary of HP Caliper Features

HP Caliper's most important features include the following:

• Performance data is automatically saved in databases, which you can use to generate reports

without having to remake the measurements. Multiple databases can also be combined for aggregated results.

• All reports are available in text format and comma-separated-value (CSV) format for use with

spreadsheets.

• The HP Caliper GUI can be used to set up measurements, initiate measurement runs, and

interactively explore collected performance data.

• Performance data can be correlated to your source program by line number.

• You can include or exclude specific load modules, such as libc, when measuring performance.

• Both per-thread and aggregated thread reports are available for most measurements.

• Performance data can be reported by function, sorted to show hot spots.

• You can perform per-process and system-wide measurements, for user or kernel space. The

system-wide measurement data can be attributed to the kernel, processes, or processes and modules, or not attributed.

• Multiprocess selection capabilities are provided.

• Limited support for dynamically generated code is provided.

• Disassembly listings (template types, symbolic branch targets, branch targets as function offsets,

optional marked branch target instructions) are provided.

• Support for command-line options from a file is provided.

• The ability to attach and detach to running processes for certain measurements is provided.

• You can use the Advisor expert system to analyze applications, using either the default rules

or rules you write yourself.

• On HP-UX, you can restrict PMU measurements to specific regions of your program.

• On HP-UX, there is full support for AAS executables (applications using Adaptive Address

Space).

20 HP Caliper at a Glance

2 Getting Started with the HP Caliper Command-Line

Interface

This chapter provides some example programs to show you how to get started using the HP Caliper command-line interface. The programs are chosen for illustration purposes and are not necessarily representative of programs you might actually want to analyze.

Example: Running fprof on a Short Program, with Default Output

HP Caliper provides many types of performance measurements. You typically specify which type of measurement to perform by the first argument to the caliper command.

A good measurement to start with is fprof (flat profile), which will show you the parts of your application that have the highest CPU usage. When you specify fprof, HP Caliper samples your application's instruction pointer (IP) at regular intervals (every 500,000 CPU cycles by default) and reports which functions and source lines incurred the most IP sample hits. Because HP Caliper uses samples, rather than precise counts, measurement intrusion is kept to a minimum.

To illustrate, let us collect fprof data on a run of an example program called matmul. First, we will compile matmul with full optimization enabled:

$ /opt/ansic/bin/cc -Aa +O3 -o matmul matmul.c

Now we will have HP Caliper collect performance data for one run of matmul:

$ caliper fprof ./matmul

Once matmul exits, HP Caliper writes a text report to stdout (by default) as shown in

Figure 2 (page 22).

The numbers (which are bold in the PDF version of this guide) are annotations to explain the report—they are not part of the output you receive. See the list at the end of the report for the explanations.

Example: Running fprof on a Short Program, with Default Output 21

Figure 2 fprof Measurement Report for matmul, with Default Report Output

================================================================================ HP Caliper 4.3.0 Report Summary for Flat Profile ================================================================================ Collection Run 1: (Flat Profile)

---------------------------------

Processor Information

Machine name: fitzroy Number of processors: 4 Processor type: Itanium2 9M Processor speed: 1600 MHz Virtual machine: no

Run Information

Configuration: /opt/caliper/config/fprof Date: May 05, 2007 Version: HP Caliper - HP-UX Itanium Version 4.3.0 (2007-05-05) OS: HP-UX B.11.23 U ia64 Database: /home/meagher/.hp_caliper_databases/fprof Measurement scope: per-process

Sampling Specification

Sampling event: CPU_CYCLES Sampling period: 500000 events Sampling period variation: 25000 (5.00% of sampling period) Sampling counter privilege: user (user-space sampling) Data granularity: 16 bytes Data sampled: IP

--------------------------------------------------------------------------

Metrics Summed for Entire Run

---------------------------------------------- PLM Event Name U..K TH Count

----------------------------------------------CPU_CYCLES x___ 0 659001879 BACK_END_BUBBLE.ALL x___ 0 99866365 BE_EXE_BUBBLE.GRALL x___ 0 1244270

----------------------------------------------PLM: Privilege Level Mask U/K = user/kernel levels (U: level 3, K: level 0) The intermediate levels (1, 2) are unused on HP-UX or Linux x : the metric is measured at the given level (_ : not measured) TH: event THreshold, determines the event counter behavior, TH == 0 : counter += event_count_in_cycle TH > 0 : counter += (event_count_in_cycle >= threshold ? 1 : 0)

----------------------------------------------% of Cycles lost due to stalls (lower is better):

15.15 = 100 * (BACK_END_BUBBLE.ALL / CPU_CYCLES)

% of Cycles stalled due to GR/GR or GR/load dependency (lower is better):

0.19 = 100 * (BE_EXE_BUBBLE.GRALL / CPU_CYCLES)

-----------------------------------------------

Process Summary

------------------------------------------% Total Cumulat IP % of IP Samples Total Samples Process

-------------------------------------------

100.00 100.00 1319 matmul (pid: 6991)

------------------------------------------[Minimum process entries: 5, percent cutoff: 2.00, cumulative percent cutoff: 100.00]

------------------------------------------================================================================================ Flat Profile Report for matmul

================================================================================

Target Application

Program: /home/meagher/matmul Invocation: ./matmul Process ID: 6991 (started by Caliper) Start time: 09:31:37 AM End time: 09:31:38 AM Termination Status: 1 Last modified: May 5, 2007 at 09:09 AM Memory model: ILP32 Processor set: default

22 Getting Started with the HP Caliper Command-Line Interface

Target Execution Time

Real time: 0.428 seconds User time: 0.415 seconds System time: 0.008 seconds

Sampling Specification

Number of samples: 1319 Data sampled: IP

Metrics Summed for Entire Run

---------------------------------------------- PLM Event Name U..K TH Count

----------------------------------------------CPU_CYCLES x___ 0 659001879 BACK_END_BUBBLE.ALL x___ 0 99866365 BE_EXE_BUBBLE.GRALL x___ 0 1244270

----------------------------------------------% of Cycles lost due to stalls (lower is better):

15.15 = 100 * (BACK_END_BUBBLE.ALL / CPU_CYCLES)

% of Cycles stalled due to GR/GR or GR/load dependency (lower is better):

0.19 = 100 * (BE_EXE_BUBBLE.GRALL / CPU_CYCLES)

-----------------------------------------------

Load Module Summary

----------------------------------------------% Total Cumulat IP % of IP Samples Total Samples Load Module

-----------------------------------------------

96.97 96.97 1279 matmul

2.88 99.85 38 libc.so.1

0.15 100.00 2 dld.so

-----------------------------------------------

100.00 100.00 1316 Total

-----------------------------------------------

Function Summary

------------------------------------------------------------------------% Total Cumulat IP % of IP Samples Total Samples Function File

-------------------------------------------------------------------------

96.97 96.97 1279 matmul::main matmul.c

2.88 99.85 38 libc.so.1::rand rand.c

------------------------------------------------------------------------[Minimum function entries: 5, percent cutoff: 0.10, cumulative percent cutoff: 100.00]

Function Details

--------------------------------------------------% Total Line| IP IP Slot| >Statement| Samples Samples Col,Offset Instruction

---------------------------------------------------

96.97 [matmul::main, 0x40009a0, matmul.c] 1279 ~38 Function Totals

----------------------------------------- [/home/meagher/matmul.c] 34 ~16 > mata[i][j] = matb[i][j] = (float) rand() ; 1 ~28 > for (k = 0 ; k < INDEX ; k++) { 1244 ~29 > matres[i][j] =

---------------------------------------------------

2.88 [libc.so.1::rand, 0x4119f60, rand.c] 38 ~57 Function Totals

----------------------------------------- [File not found: /ux/libsobj_i380em/libs/libc/shared_em_32/obj/../../../ ../../core/libs/libc/shared_em_32/../core/gen/rand.c]

---------------------------------------------- 4 ~57 > 11 ~61 > 18 ~77 >

Example: Running fprof on a Short Program, with Default Output 23

3 ~83 >

--------------------------------------------------[Minimum function entries: 0, percent cutoff: 1.00, cumulative percent cutoff: 100.00]

HP Caliper 4.3.0: Report Summary for Flat Profile: The heading for the report, including the HP Caliper version number and the measurement (Flat Profile).

Collection Run 1: (Flat Profile): The heading for the run.

Processor Information: Information about your processor.

Run Information: Information about the run.

Sampling Specification: Information about what was being measured.

Metrics Summed for Entire Run: Metrics for the entire run are summed:

• CPU_CYCLES is the number of elapsed processor cycles. (CPU_CYCLES is known as

CPU_OP_CYCLES.ALL on the Integrity servers dual-core Itanium 2 and Itanium 9300 quad-core processors.)

• BACK_END_BUBBLE.ALL is full pipe bubbles in the main pipe.

• BE_EXE_BUBBLE.GRALL is full pipe bubbles in the main pipe due to execution unit stalls.

Process Summary:

Flat Profile Report for matmul: This is a low-level report for the single process that is measured for this collection run.

For each collection run, one low-level report is produced for each process. A low-level report can be: data for a single process, data for a group of “matching” processes, or a module-centric view of all processes.

Target Application: Information about your application.

Target Execution Time: How long the run took.

Sampling Specification: Information about what was being measured.

Metrics Summed for Entire Run: Metrics for the entire run are summed. CPU_CYCLES is the number of elapsed processor cycles. (CPU_CYCLES is known as CPU_OP_CYCLES.ALL on the Integrity servers dual-core Itanium 2 and Itanium 9300 quad-core processors.) BACK_END_BUBBLE.ALL is full pipe bubbles in the main pipe. BE_EXE_BUBBLE.GRALL is full pipe bubbles in the main pipe due to execution unit stalls.

Load Module Summary:

• % Total IP Samples: Percent of the total IP samples attributable to a particular load

module.

• Cumulat % of Total: Running sum of the percent of total IP samples account for by the

particular load module and those listed above it.

• IP Samples: Total number of IP samples attributed to the particular load module.

Function Summary:

• % Total IP Samples: Percent of the total IP samples attributable to a particular function.

• Cumulat % of Total: Running sum of the percent of total IP samples account for by the

particular function and those listed above it.

• IP Samples: Total number of IP samples attributed to the particular function.

Function Details:

• % Total IP Samples: Percent of the total IP samples attributable to a particular function.

• IP Samples: Total number of IP samples attributed to the particular function.

24 Getting Started with the HP Caliper Command-Line Interface

• Line | Slot | Col,Offset

The column contains one of these:

◦ A source-code line number for rows showing statements

◦ An instruction slot number for rows showing instructions not on a bundle boundary

◦ A source-code column number followed by an offset from the beginning address

of a function for rows showing instructions on a bundle boundary

• >Statement | Instruction: The column contains either a source statement, preceded by

“>”, or a disassembled instruction. Statements that are out of order due to optimization are preceded by “*>”.

“File not found” error: Here, the application called a routine in libc, but the source code for that library routine is not available. This is a common error and you can usually ignore it.

Example: Adding Instructions to an fprof Report

Notice that, by default, only source statements were shown in the Function Details section. If you would also like to see disassembled instructions, then you can re-report the collected data using the -r option. The -r option takes one of the following qualifiers: statement (report source statements), instruction (report disassembled instructions), or all (report both source and instructions).

HP Caliper saves the latest collected data and uses that by default when generating a report. It does not re-run the application and collect new data.

We will also specify an output file using the -o option:

$ caliper fprof -o out.txt -r all

In the resulting report output file (out.txt), you will find an fprof report that shows IP sample counts down to the instruction level. “fprof Measurement Report for matmul, with IP Sample Counts

for One Function” (p. 26) shows a section of the report that contains IP sample counts for one

function. The numbers (which are bold in the PDF version of this guide) are annotations to explain the

report—they are not part of the output you receive. See the list at the end of the report for the explanations.

Example: Adding Instructions to an fprof Report 25

Figure 3 fprof Measurement Report for matmul, with IP Sample Counts for One Function

Function Details

--------------------------------------------------% Total Line| IP IP Slot| >Statement| Samples Samples Col,Offset Instruction

---------------------------------------------------

96.88 [matmul::main, 0x40009a0, matmul.c] 1275 ~38 Function Totals

------------------------------------------

[/home/meagher/matmul.c]

(32) ~16 *> mata[i][j] = matb[i][j] = (float) rand() ; ~9,0x0280:0 M nop.m 0 :1 M nop.m 0 :2 F_(p6) fcvt.xf f6=f6 ;;

2 ~9,0x0290:0 M nop.m 0 :1 M nop.m 0 :2 F_ fma.s f6=f6,f1,f0 ;; ~9,0x02a0:0 M stfs [r47]=f6,4 :1 M stfs [r48]=f6,4 :2 B_ br.call.sptk.many rp=b7 ;;

~ ~ ~ ~ ~ ~ ~ ~ ~9,0x02e0:0 M nop.m 0 :1 M nop.m 0 :2 F_(p6) fcvt.xf f6=f6 ;; 4 ~9,0x02f0:0 M nop.m 0 :1 M nop.m 0 :2 F_ fma.s f6=f6,f1,f0 ;; ~9,0x0300:0 M stfs [r47]=f6,4 :1 M stfs [r48]=f6,4 :2 B_ br.call.sptk.many rp=b7 ;; . . . .

---------------------------------------------------

3.04 [libc.so.1::rand, 0x4119f60, rand.c] 40 ~57 Function Totals

------------------------------------------

1 2

Identifies the function (main) for which disassembly is shown. Specifies the function's load module (matmul), starting address (0x40009a0), and source file (matmul.c.

Shows total IP sample hits (1275) and starting line number (38) for the function. A tilde (~) preceding a line number (~38) indicates that the line number is approximate due to optimization.

Names the source file of function main.

Shows sample IP hits (41) for statement at line 16 (~ indicates the line number is approximate due to optimization) of matmul.c. Sample IP hits for statements are shown in parentheses; sample IP hits for instructions are not.

Source lines are preceded by >. If a source line is out of order or is associated with multiple, noncontiguous instructions, the source line is also preceded by an asterisk (*>).

Shows sample IP hits (4) for the instruction bundle starting at function offset 0x0290, where the associated source column is ~9 (~ indicates the source column is approximate due to optimization). Instructions are preceded by template information: in this case, M for slot 0 and slot 1, and F_ for slot 2.

Shows a discontinuity marker, which indicates that some instruction bundles without associated data have been left out of the report. (To report all disassembly, use the --context-lines option.)

26 Getting Started with the HP Caliper Command-Line Interface

Types of Measurements

HP Caliper is capable of three types of performance measurement:

• A global measurement of total run metrics

• A sampled measurement based on the granularity you specify

• A precise measurement of every execution path in your code (HP-UX only)

See Table 1 (page 44).

Global Measurement

A global measurement gives you a single value for a specific metric of your program, such as total CPU time used.

The only global measurement available in HP Caliper is ecount (total CPU time). A global measurement is best used for:

• Comparing the effect of different types of test data that your program processes

• Comparing the benefits of different compile-time optimization settings

• Detecting performance regressions caused by program modifications

You can use a global measurement to help you identify what performance areas of your program to investigate further.

The advantage of a global measurement is that it does not affect your program's performance. The disadvantage of a global measurements is that it does not identify specific parts of your program

that might benefit from optimization.

Sampled Measurements

A sampled measurement measures your program's performance at regular intervals, based on CPU events, recording the current program location and selected performance metrics.

A sampled measurement is best used for:

• Identifying where your program is spending time

• Identifying approximately where events such as cache misses occur

• Determining the performance effect and location of branch mispredictions

You can use sampled measurements to focus your analysis on specific parts of your program. The advantage of sampled measurements is that they can help you localize performance issues in

your program. The disadvantage is that they might miss very fast, seldom-called code. You might need to adjust

HP Caliper settings, such as the sampling frequency, to help locate events in your code. Sampled measurements also require more resources, such as system memory, which might affect

the run-time performance of your program or limit the amount of information you can collect. You can control the tradeoff between resource usage and accuracy of the results by changing the

sample interval.

Precise Measurements

A precise measurement gives you exact information about what is happening and where events are happening in your program. When you use a precise measurement, HP Caliper dynamically instruments your binary program while it is running to enable the collection of information.

Types of Measurements 27

Precise measurements are best used for:

• Identifying the most and least used functions in your program

• Identifying all the branch paths executed in the program

Collecting precise measurements requires more system resources than sampled measurements. Collecting precise measurements also affects the performance of the program being measured. The performance effects may vary from a few percent to 300 percent, depending on how much measurement you request. These performance effects mean that programs making assumptions about the running time of their code might behave differently when run under HP Caliper.

What to Look for in Using HP Caliper

A useful approach for tuning performance is to start with easy-to-perform global measurements to identify likely areas for tuning. Then you can use more specific measurements on areas of concern.

For example, you might start by making global measurements on a variety of events, such as:

• CPU cycles

• Instruction execution counts

• Data cache misses

• Instruction cache misses

• Branch mispredictions

The results of the global measurements will quickly identify which factors most affect your program's performance.

The next step is to make sampled measurements on the top performance factors you have identified. You can vary the sample rates to find the approximate location of the problem or problems. Usually,

this is sufficient to locate trouble spots. You can also focus on hot spots. A hot spot is an instruction or set of instructions that has a higher

execution count than most other instructions in a program. For example, code that is inside a loop will likely be executed more times than straight-line code. Usually the “hotness” is measured with CPU cycles, but it could also be measured with metrics such as cache misses.

When tuning performance, you first focus on hot spots because a small change in a hot spot, multiplied by its higher execution frequency, produces a larger improvement than making the same change in an instruction that is rarely executed.

Here are some useful things to look for in a report:

• If the percent of cycles lost due to stalls (in the Metrics Summed for Entire Run) is high—greater

than 50 percent—the program's performance could probably be improved.

• Although the values in the IP Samples column of the Function Details do not represent actual

execution counts, you can still use the values as a relative ranking of how often particular lines are executed. The IP Samples values will vary slightly with each run, but they can help you identify which parts of your code have the most effect on your application's performance.

Syntax for caliper Command

The basic command-line syntax for making measurements with HP Caliper is:

caliper measurement [caliper_options] program [program_arguments]

where: measurement The name of a measurement that contains information about what you

want HP Caliper to measure and report. For more information, see “HP Caliper Measurement Configuration

Files” (p. 43).

28 Getting Started with the HP Caliper Command-Line Interface

caliper_options Parameters used to customize the performance analysis.

For more information, see “HP Caliper Options” (p. 48).

program The name of the executable program you want HP Caliper to measure. program_arguments Any number of arguments expected by your executable.

You can use an options file to specify command-line information, including the measurement, options, program, and program arguments. See “-f or --options-file” (p. 50) for details.

For more information, see “Configuring HP Caliper ” (p. 92).

Basic Tasks: A Quick Reference

Here is a list of basic tasks and the HP Caliper commands you can use to perform them.

Starting HP Caliper

Once installed, the easiest way to access HP Caliper is to type caliper. For example:

$ caliper myprog

This runs the default measurement, scgprof, on your program in your current directory and produces a text report to stdout. To run another measurement, just type it:

$ caliper fcount myprog

Stopping HP Caliper

To stop HP Caliper before it finishes measuring your program, enter Ctrl-C, or from another process use this command:

$ kill -s INT caliper_process_ID

Either of these methods stops the measurement run. HP Caliper then processes the data collected up to the point where it was stopped and generates a report. There could be a significant delay before the HP Caliper process terminates.

To stop HP Caliper immediately, without generating data, use this command:

$ kill -s TERM caliper_process_ID

CAUTION: If HP Caliper is measuring processes using instrumentation on HP-UX (that is, generating

a precise measurement), stopping HP Caliper will cause it to forcibly terminate all processes that are being measured. Any resources used by the processes, such as shared memory segments, temporary files, and so forth, will not be cleaned up.

For PMU-only measurements, HP Caliper will simply detach from the processes and stop. The processes will continue normally.

Showing HP Caliper Options

For HP Caliper short help, including a list of the most commonly used options and measurements, use:

$ caliper -h

For HP Caliper long help, use:

$ caliper -H

Creating a Call Graph Profile with HP Caliper

To create a call graph profile with HP Caliper, use either of these commands:

$ caliper scgprof [caliper_options] program [program_arguments]

$ caliper cgprof [caliper_options] program [program_arguments]

Basic Tasks: A Quick Reference 29

The first command produces a call graph by sampling. The second command (on HP-UX only) produces an exact call graph. They both produce an enhanced gprof-like output.

Creating a Text Report for Analysis

To save the report produced by HP Caliper to a file, specify an output file name:

$ caliper measurement -o filename [caliper_options] program [program_arguments]

Creating a Report Based on Your Collected Data

By default, HP Caliper saves the results of a measurement to a database. This allows you to generate reports with different settings without having to re-run your application.

To create reports based on the database, specify the caliper report command and the report options you want to use. For example, the following command creates a report based on the last database you created:

$ caliper report [caliper_report_options]

For more information, see “How HP Caliper Saves Data in Databases” (p. 115).

Using the HP Caliper Advisor

One way to get started using HP Caliper quickly is to use the HP Caliper Advisor. See “Using the

HP Caliper Advisor” (p. 77).

Restrictions on Using HP Caliper

Some restrictions are:

• When HP Caliper detaches from a process, it can affect the I/O relationship between the user

and that process. An example is an application that reads stdin from the user; e.g., caliper ecount top If HP Caliper is sent a SIGINT (or the --duration option is given), it will

detach from the 'top' process, which will break the I/O between the user and 'top'. Text typed into the terminal window will no longer be sent to the 'top' process, and the curses library used by 'top' will break the stty settings in the terminal window.

• Shared library support does not include instrumented measurements ( cgprof, and fcount

measurements) of the dld.so and uld.so system libraries.

• It is not possible to debug an application while it is being measured by HP Caliper.

• These measurements measure and report only aggregated results of multithreaded programs:

ecount•

• fcount

• fcover

• HP Caliper only measures native Integrity servers programs, not PA-RISC programs running

in emulation mode.

• HP Caliper might not be able to measure handwritten assembly code that performs address

arithmetic or does not follow the standard run-time conventions.

• HP Caliper cannot make measurements for dynamically generated code with these

measurements:

• cgprof

• fcount

• fcover

30 Getting Started with the HP Caliper Command-Line Interface

+ 247 hidden pages