Index

_pmID_int structure
Data Structures

_pmInDom_int structure
Data Structures

access controls
Configuring the Trace PMDA

Applicatin Programming Interface
Application Interaction

application interaction
Application Interaction

Application Programming Interface
The Trace API
PMAPI—The Performance Metrics API

architecture of PCP
Performance Co-Pilot Architecture

archive log
Retrospective Sources of Performance Metrics

archive log
PMAPI Time Control Services
Retrospective Sources of Performance Metrics
pmGetArchiveEnd
Current PMAPI Context
pmStore
pmGetInDomArchive
PMAPI Context Services
PMAPI—The Performance Metrics API

archive logging
Instrumenting Applications to Export Performance Data

array
Distributed Collection
N Dimensional Data
Performance Metrics Values
Data Structures
Variable Length Argument and Results Lists

asynchronous trace protocol
Configuring the Trace Library
Configuring the Trace Library

audience type
Intended Audience

automated alarms
Instrumenting Applications to Export Performance Data

caching PMDA
Caching PMDA
Latency and Threads of Control

Cisco
Distributed Collection
Caching PMDA

client development for PCP
Client Development and PMAPI

cluster
Namespace

collection host
Distributed Collection

collection time
Current PMAPI Context
pmWhichContext
pmNewContext

collection tools
Performance Co-Pilot Architecture

collector
Performance Co-Pilot Architecture

COLOR_INDOM
Example—Several Metrics and an Instance Domain, the Simple PMDA

computation state
Instrumenting Applications to Export Performance Data

configuring PCP tools
Configuring PCP Tools

content overview
What This Guide Contains

counter semantics
Example—The effect of semantics on a metric

customers
Instrumenting Applications to Export Performance Data

daemon process
The Daemon Process Method

daemon PMDA
Daemon PMDA
The Daemon Process Method

daemon PMDA initialization
Daemon Initialization

daemon process
The Daemon Process Method

data export
Instrumenting Applications to Export Performance Data

debugging aid
Configuring the Trace Library

debugging and testing
Testing and Debugging a PMDA

debugging flags in pmcd
Debugging Information

delays in gathering performance data
Latency and Threads of Control

developing a PMDA
PMDA Development

diagnostic messages
Configuring the Trace Library

diagnostic output
Configuring the Trace Library

disadvantages of DSO PMDA
Daemon PMDA

discrete semantics
Example—The effect of semantics on a metric

distributed collection
Distributed Collection

distributed operation
Distributed Collection

distributed performance management
Instrumenting Applications to Export Performance Data

distributed performance metrics collection
Distributed Collection

distributed PMNS
Distributed PMNS

dlopen
The In-Process (DSO) Method
DSO PMDA

domain
Namespace
Namespace

domain number
Domains

domains, defined
Overview

dometric function
pmTraversePMNS

DSO
Procedure Checklist
DSO PMDA
The In-Process (DSO) Method
Acronyms

DSO PMDA
DSO Interface
The In-Process (DSO) Method
DSO PMDA

DSO PMDA initialization
Common Initialization

Dynamic Shared Object
The In-Process (DSO) Method

dynamically attached library
PMDA Architecture

embedded calls
Instrumenting Applications to Export Performance Data

environment variables
Configuring the Trace Library
Instrumenting Applications to Export Performance Data

evolution of a PMDA
Management of Evolution within a PMDA

Examples
Trace PMDA

execv
Daemon PMDA

exporting data from a PMDA
Extracting the Information
Implementing a PMDA

filename
pmLoadNameSpace

flags
Configuring the Trace Library

fork
Daemon PMDA

Glossary of Acronyms
Acronyms

handle context
pmReconnectContext

help text for PMDA
PMDA Help Text

historical buffers
Rolling-Window Periodic Sampling

historical buffers
Simple Periodic Sampling
Configuring the Trace PMDA

identification tag
Application Interaction

independent software vendors
Instrumenting Applications to Export Performance Data

indom instance domain
pmGetInDomArchive
pmAddProfile
pmLookupInDomText

instance domain refresh
Configuring the Trace PMDA

instance identifier
Performance Metric Instances
PMAPI Context Services

instance profile
pmWhichContext

instances and instance domains
Performance Metric Instances
Instances

instances, defined
Overview

instantaneous semantics
Example—The effect of semantics on a metric

instlist argument
pmAddProfile
pmGetInDomArchive
pmGetInDom

instrumenting applications
Instrumenting Applications to Export Performance Data

integrating a PMDA
Integration of PMDA

intended audience
Intended Audience

internal instance identifier
Performance Metrics Values

Internet resources
Resources for Further Information

interprocess communication
Application Interaction

interprocess communication
Configuring the Trace Library
PMDA Architecture
Implementing a PMDA

IP
Acronyms

IPC
The In-Process (DSO) Method

item number
Namespace
Namespace

languages
Instrumenting Applications to Export Performance Data

latency and threads of control
Latency and Threads of Control

leaf node
pmTraversePMNS

libpcp_trace libary
interrelationships
Instrumenting Applications to Export Performance Data

libpcp_trace library
instrumenting applications
Trace PMDA

libpcp_trace library
Application Programming Interface
The Trace API
debugging aid
Configuring the Trace Library
entry points
Configuring the Trace Library

libpcp_trace routines
Configuring the Trace Library

library libpcp_trace
Trace PMDA

Makefile
Installing a PMDA

metric instances
Performance Metric Instances

metrics, defined
Overview

monitor
Performance Co-Pilot Architecture

monitoring tools
Performance Co-Pilot Architecture

multidimensional arrays
N Dimensional Data

name
pmNameInDom
pmTraversePMNS

namelist
pmGetInDom
pmGetInDomArchive

namespace (PMNS)
Distributed PMNS

newhelp command
PMDA Help Text

NOW_INDOM
Example—Several Metrics and an Instance Domain, the Simple PMDA

observation metric units
Configuring the Trace PMDA

offspring
pmGetChildren

overview of contents
What This Guide Contains

parallelism
Instrumenting Applications to Export Performance Data

PCP
Acronyms
architecture
Performance Co-Pilot Architecture
client development
Client Development and PMAPI
definition
About This Guide

PCP_TRACE_HOST variable
Configuring the Trace Library

PCP_TRACE_PORT variable
Configuring the Trace Library

PCP_TRACE_RECONNECT variable
Configuring the Trace Library

PCP_TRACE_REQTIMEOUT variable
Configuring the Trace Library

PCP_TRACE_TIMEOUT variable
Configuring the Trace Library

PDMA
checklist
Procedure Checklist
installing
Installing a PMDA

PDU
Acronyms
Overview

PDU_DESC_REQ
Overview

PDU_FETCH
Example—simple_init in the Simple PMDA
Overview

PDU_INSTANCE_REQ
Overview

PDU_PROFILE
Overview

PDU_RESULT
Overview
Example—simple_init in the Simple PMDA

PDU_TEXT_REQ
Overview

performance metric
dimensionality
Performance Metric Descriptions
dimensionality and scale
Performance Metric Descriptions
scale
Performance Metric Descriptions

Performance Metric Identifier (PMID)
Namespace

Performance Metrics API (PMAPI)
Introduction

performance metrics collection daemon (pmcd)
Performance Co-Pilot Architecture
Implementing a PMDA

Performance Metrics Collection System
Client Development and PMAPI

Performance Metrics Domain Agent (PMDA)
Introduction

pipe
Daemon PMDA
DSO PMDA
Example—Install Simple PMDA as a Daemon

PM_CONTEXT_ARCHIVE
pmNewContext

PM_CONTEXT_HOST
pmNewContext

PM_ERR_CONV error code
pmExtractValue
Management of Evolution within a PMDA

PM_ERR_INST error code
Example—simple_store in the Simple PMDA

PM_ERR_PMID error code
Management of Evolution within a PMDA
Example—simple_store in the Simple PMDA

PM_ERR_SIGN error code
pmExtractValue

PM_ERR_TIMEOUT error code
pmFetch

PM_ERR_TRUNC error code
pmExtractValue

PM_IN_NULL
Performance Metric Instances

PM_INDOM_NULL
pmAddProfile
Example—A Single Metric, the Trivial PMDA
Example—Several Metrics and an Instance Domain, the Simple PMDA
Performance Metric Instances

PM_SEM_COUNTER semantic type
Semantics

PM_SEM_DISCRETE semantic type
Semantics

PM_SEM_INSTANT semantic type
Semantics
Example—A Single Metric, the Trivial PMDA

PM_TEXT_HELP
pmLookupInDomText
pmLookupText

PM_TEXT_ONELINE
pmLookupInDomText
pmLookupText

PM_TYPE_AGGREGATE
Performance Metric Descriptions

PM_TYPE_NOSUPPORT
Performance Metric Descriptions
Management of Evolution within a PMDA

PM_TYPE_STRING
Performance Metric Descriptions
pmExtractValue

PM_TYPE_U32
Example—A Single Metric, the Trivial PMDA

PM_VAL_INSITU
Performance Metrics Values

pmAddProfile routine
pmAddProfile
PMAPI Context Services

PMAPI
PMAPI—The Performance Metrics API
Acronyms
Ancillary Support Services
PMAPI Ancillary Support Services
Application Compiling and Linking
Compiling and Linking PMAPI Applications
Archive Services
PMAPI Archive-Specific Services
argument lists
Variable Length Argument and Results Lists
Context Services
PMAPI Context Services
current context
Current PMAPI Context
Description Services
PMAPI Metric Description Services
error handling
Handling PMAPI Errors
error handling
PMAPI Error Handling
Identifying metrics
Naming and Identifying Performance Metrics
Initializing New Metrics
Initializing New Metrics
Instance Domain Services
PMAPI Instance Domain Services
Iterative Processing of Values
Iterative Processing of Values
metric descriptions
Performance Metric Descriptions
metric instances
Performance Metric Instances
metric values
Performance Metrics Values
naming metrics
Naming and Identifying Performance Metrics
procedural interface
PMAPI Procedural Interface
Program Evolution
Accommodating Program Evolution
programming style
General Issues of PMAPI Programming Style and Interaction
results list
Variable Length Argument and Results Lists

PMAPI Programming Issues
PMAPI Programming Issues and Examples

pmAtomStr routine
Management of Evolution within a PMDA
pmAtomStr

pmAtomValue structure
Example—simple_fetchCallBack in the Simple PMDA

pmcd
Domains
Acronyms
Performance Co-Pilot Architecture
Distributed Collection
The In-Process (DSO) Method
Distributed Collection

PMCD_RECONNECT_TIMEOUT variable
pmReconnectContext

PMCD_REQUEST_TIMOUT variable
pmFetch

pmchart tool
Configuring the Trace PMDA

pmConvScale routine
pmConvScale
Management of Evolution within a PMDA

PMDA
Acronyms

PMDA architecture
PMDA Architecture
PMDA Architecture

PMDA development
PMDA Development
initialization of a PMDA
Initializing a PMDA
Install script
Installing a PMDA
Upgrading a PMNS to Include Metrics From a New PMDA
installing a PMDA
Integration of PMDA
pmdaDesc callback
Overview
pmdaExt structure
pmdaExt
Overview
pmdaFetch callback
Overview
pmdaIndom structure
Data Structures
pmdaInit routine
Common Initialization
pmdaInstance callback
Overview
pmdaInstid structure
Data Structures
pmdaInterface structure
pmdaInterface
Overview
pmdaMetric structure
Data Structures
pmdaProfile callback
Overview
pmdaStore callback
Overview
Example—simple_store in the Simple PMDA
pmdaText callback
Overview

PMDA help text
PMDA Help Text

PMDA_PMID macro
Data Structures

pmDelProfile routine
pmDelProfile
PMAPI Context Services

pmDesc structure
Data Structures
Performance Metric Descriptions
Management of Evolution within a PMDA
Performance Metric Descriptions

pmDestroyContext routine
pmDestroyContext

pmDupContext routine
PMAPI Context Services
pmDupContext

pmErrStr routine
pmErrStr

pmExtractValue routine
Management of Evolution within a PMDA
pmExtractValue
pmConvScale

pmFetch routine
PMAPI Context Services
pmPrintValue
pmSortInstances
pmFetchArchive
Symbolic Association Between a Metric's Name and Value
Management of Evolution within a PMDA
Variable Length Argument and Results Lists
Performance Metrics Values
pmSetMode
pmFetch
Performance Metrics Values
pmFetch
pmNewContext
pmFreeResult

pmFetchArchive routine
PMAPI Context Services
pmSetMode
pmFetchArchive

pmFreeResult routine
pmFetch
pmFreeResult
Variable Length Argument and Results Lists

pmGetArchiveEnd routine
PMAPI Context Services
pmGetArchiveEnd

pmGetArchiveLabel routine
PMAPI Context Services
pmGetArchiveLabel

pmGetChildren routine
Variable Length Argument and Results Lists
pmGetChildren
pmGetChildrenStatus
PMAPI Context Services

pmGetChildrenStatus routine
PMAPI Context Services

pmGetInDom routine
pmGetInDom
pmSetMode
Variable Length Argument and Results Lists
pmGetInDomArchive
PMAPI Context Services

pmGetInDomArchive routine
pmGetInDomArchive
pmGetInDomArchive
PMAPI Context Services

pmGetPMNSLocation routine
PMAPI Context Services
pmGetPMNSLocation

PMID
Acronyms

pmIDStr routine
pmIDStr

pmInDomStr routine
pmInDomStr

pmLoadNameSpace routine
pmLoadNameSpace
pmLoadASCIINameSpace

pmLookupDesc routine
pmConvScale
pmSetMode
pmLookupDesc
PMAPI Context Services
pmExtractValue
Management of Evolution within a PMDA

pmLookupInDom routine
pmLookupInDom
PMAPI Context Services
pmSetMode

pmLookupInDomArchive routine
pmLookupInDomArchive
PMAPI Context Services

pmLookupInDomText routine
PMAPI Context Services
pmLookupInDomText

pmLookupName routine
PMAPI Context Services
Symbolic Association Between a Metric's Name and Value
pmLookupName

pmLookupText routine
pmLookupText
Variable Length Argument and Results Lists
PMAPI Context Services
Management of Evolution within a PMDA

PMNS
distributed
Distributed PMNS

pmNameAll routine
pmNameAll

pmNameID routine
Variable Length Argument and Results Lists
pmNameID
PMAPI Context Services

pmNameInDom routine
pmSetMode
Variable Length Argument and Results Lists
pmNameInDom
PMAPI Context Services

pmNameInDomArchive routine
pmNameInDomArchive
PMAPI Context Services

pmNewContext routine
pmNewContext

pmNewContextZone function
pmNewContextZone

PMNS
Acronyms

pmns file defines namespace
Namespace

pmPrintValue routine
pmPrintValue
Management of Evolution within a PMDA

pmReconnectContext routine
pmReconnectContext

pmSetMode routine
PMAPI Context Services
pmSetMode
pmGetArchiveEnd

pmStore routine
Performance Metrics Values
pmStore
pmStore
Management of Evolution within a PMDA
PMAPI Context Services

PMTRACE_STATE_API flag
Configuring the Trace Library

PMTRACE_STATE_ASYNC flag
Configuring the Trace Library

PMTRACE_STATE_COMMS flag
Configuring the Trace Library

PMTRACE_STATE_NOAGENT flag
Configuring the Trace Library
Configuring the Trace Library

PMTRACE_STATE_NONE flag
Configuring the Trace Library

PMTRACE_STATE_PDU flag
Configuring the Trace Library

PMTRACE_STATE_PDUBUF flag
Configuring the Trace Library

pmtraceabort function
Transactions

pmtracebegin function
Transactions

pmtracend function
Transactions

pmtraceobs function
Observations

pmtracepoint function
Point Tracing
Observations

pmtracestate call
Configuring the Trace Library

pmTraversePMNS routine
pmTraversePMNS
PMAPI Context Services

pmTrimNameSpace routine
PMAPI Context Services
pmTrimNameSpace

pmTypeStr routine
Management of Evolution within a PMDA
pmTypeStr

pmUnitsStr routine
pmUnitsStr

pmUnloadNameSpace routine
pmUnloadNameSpace

pmUseContext routine
pmUseContext
pmNewContext

pmWhichContext routine
pmWhichContext

point tracing
Point Tracing

procedure for implementing PMDA
Procedure Checklist

Programming Interface
PMAPI—The Performance Metrics API

protocol
Configuring the Trace Library

protocol data unit
Application Interaction

Protocol Data Unit (PDU)
Overview

Protocol Data Units
Configuring the Trace Library

removing a PMDA
Removing a PMDA

requirements for PMDA design
Implementing a PMDA

restarting pmcd
Installing a PMDA

ring buffer
Rolling-Window Periodic Sampling

rolling-window sampling
accurate representation
Sampling Techniques
advantage
Rolling-Window Periodic Sampling
buffers
Rolling-Window Periodic Sampling
example
Rolling-Window Periodic Sampling Example
metrics affected
Sampling Techniques
working buffer
Rolling-Window Periodic Sampling

sample duration
Rolling-Window Periodic Sampling
Configuring the Trace PMDA

sampling techniques
Sampling Techniques

script to remove a PMDA
Removing a PMDA

selection of metrics and instances
Overview

semantic types for a metric
Semantics

sequential log file
Implementing a PMDA

service time
Instrumenting Applications to Export Performance Data

shell process
The Shell Process Method

simple periodic sampling
Simple Periodic Sampling

simple PMDA
2 branches, 4 metrics
Example—pmns File for the Simple PMDA
4 metrics, 3 instances
Example—Several Metrics and an Instance Domain, the Simple PMDA
as daemon
Example—Install Simple PMDA as a Daemon
as DSO
Example—Install Simple PMDA as a DSO
callback for pmdaFetch
Example—simple_fetchCallBack in the Simple PMDA

simple_init function
Example—simple_init in the Simple PMDA
Example—simple_fetchCallBack in the Simple PMDA
Example—Install Simple PMDA as a DSO

simple_store function
Example—simple_store in the Simple PMDA
Example—simple_store in the Simple PMDA
Example—Log Stores Into simple.numfetch in the Simple PMDA

snapshot file
Implementing a PMDA

specific instance domain
PMAPI Context Services

sproc control threads
Latency and Threads of Control

state flags
Configuring the Trace Library
Configuring the Trace Library

storage of metrics
Metrics

stub version
Instrumenting Applications to Export Performance Data

synchronous protocol
Configuring the Trace Library

target domain
Metrics
Extracting the Information
Implementing a PMDA

TCP
Acronyms

TCP/IP port number
Configuring the Trace Library

testing and debugging
Testing and Debugging a PMDA

toolkit approach
Instrumenting Applications to Export Performance Data

trace PMDA
Trace PMDA
command-line options
Configuring the Trace PMDA
design
Trace PMDA
design
Trace PMDA Design

trace.control.reset metric
Configuring the Trace PMDA

trace.observe metrics
Observations

trace.observe.rate
Sampling Techniques

trace.point.count metric
Point Tracing

trace.point.rate
Sampling Techniques

trace.point.rate metric
Point Tracing

trace.transact.ave_time
Sampling Techniques

trace.transact.ave_time metric
Transactions

trace.transact.count metric
Transactions

trace.transact.max_time
Sampling Techniques

trace.transact.max_time metric
Transactions

trace.transact.min_time
Sampling Techniques

trace.transact.min_time metric
Transactions

trace.transact.rate
Sampling Techniques

trace.transact.rate metric
Transactions

trace.transact.total_time metric
Transactions

transactions
Transactions

trivial PMDA
Example—A Single Metric, the Trivial PMDA

trivial PMDA with callbacks
Example—trivial_fetchCallBack in the Trivial PMDA

trivial_init function
Example—trivial_init in the Trivial PMDA
Example—trivial_fetchCallBack in the Trivial PMDA

two or three dimensional arrays
N Dimensional Data

type field
pmNewContext
pmExtractValue
pmConvScale
pmPrintValue
Management of Evolution within a PMDA
Management of Evolution within a PMDA
Performance Metric Descriptions

typographic conventions
Conventions Used in This Guide

unavailable metrics support
Management of Evolution within a PMDA

visualization
Instrumenting Applications to Export Performance Data

Web pages about PCP
Resources for Further Information

working buffer
Rolling-Window Periodic Sampling
Application Interaction