diff options
Diffstat (limited to 'man/man5/pmns.5')
| -rw-r--r-- | man/man5/pmns.5 | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/man/man5/pmns.5 b/man/man5/pmns.5 new file mode 100644 index 0000000..6d6c82c --- /dev/null +++ b/man/man5/pmns.5 @@ -0,0 +1,252 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNS 5 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmns\f1 \- the performance metrics name space +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +.I $PCP_VAR_DIR/pmns +.SH DESCRIPTION +When using the Performance Metrics Programming Interface (PMAPI) +of the Performance Co-Pilot (PCP), +performance metrics are identified by an external name in a +hierarchic Performance Metrics Name Space (PMNS), and an +internal identifier, the Performance Metric Identifier (PMID). +.PP +A PMNS specifies the association between a metric's name and its PMID. +.PP +A PMNS is defined on one or more ASCII source files. +.PP +Loading of a PMNS is done by calling +.BR pmLoadNameSpace (3) +or +.BR pmLoadASCIINameSpace (3). +.PP +By default duplicate PMIDs are not allowed in the PMNS, +although +.BR pmLoadASCIINameSpace (3) +provides an alternative interface with user-defined control +over the processing of duplicate PMIDs in the PMNS. +The external format for a PMNS conforms to the syntax +and semantics described in the following sections. +.PP +There is one default PMNS in the files below +.IR $PCP_VAR_DIR/pmns , +although users and application developers are free to +create and use alternate PMNS's. +For an example of this, see +the PCP Tutorial in +.IR $PCP_DEMOS_DIR/Tutorial . +.PP +Although an application can call +.BR pmLoadNameSpace (3), +normally this is only done directly for the +.B \-n +command line option where an explicit root PMNS file is specified. +Since PCP version 2 uses a distributed PMNS (see below), +an application can extract PMNS information from a +host's PMCD or an archive. If the PMNS source +is a version 1 archive (see +.BR PCPIntro (1)), +however, +then the local PMNS will be loaded using the path specified by the +environment variable +.BR PMNS_DEFAULT . +.SH DISTRIBUTED PMNS +In PCP version 1, the PMNS functions in the API all operated on +a PMNS loaded locally from a file. Since PCP version 2, however, +PMNS functions may get the PMNS information remotely from a PMCD +or directly from the meta data of an archive. +.SH PROCESSING FRAMEWORK +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +The PMNS specification is initially passed through +.BR pmcpp (1). +This means the following facilities may be used in the specification +.IP + 3n +C-style comments +.IP + 3n +.CW #include +directives +.IP + 3n +.CW #define +directives and macro substitution +.IP + 3n +conditional processing via +.CW #ifdef +\&... +.CW #endif , +etc. +.PP +When +.BR pmcpp (1) +is executed, the ``standard'' include directories are the current directory and +.IR $PCP_VAR_DIR/pmns . +.SH SYNTAX +The general syntax for a non-leaf node in the PMNS is as follows +.PP +.ft CW +.nf +pathname { + name [pmid] + ... +} +.fi +.ft R +.PP +Where +.CW pathname +is the full pathname from the root of the PMNS to this non-leaf node, +with each +component in the pathname separated by a ``.''. +The root node for the PMNS must have the special +name ``root'', but the common prefix ``root.'' must be omitted from +all pathnames. +Each component in the pathname must begin with an alphabetic character, +and be followed by zero or +more characters drawn from the alphabetics, the digits and the underscore +``_'') character. +For alphabetic characters in a pathname component, upper and lower case are distinguished. +.PP +Non-leaf nodes in the PMNS may be defined in any order. +.PP +The descendent nodes are defined by the set of +.CW names , +relative to the +.CW pathname +of their parent non-leaf node. For the descendent nodes, leaf +nodes have a +.CW pmid +specification, non-leaf nodes do not. The syntax for +the +.CW pmid +specification has been chosen to help manage the allocation of +PMIDs across disjoint and autonomous domains +of administration and implementation. Each +.CW pmid +consists of 3 integer +parts, separated by colons, e.g. 14:27:11. This hierarchic numbering +scheme is intended to mirror the implementation hierarchy of +performance metric domain, metrics cluster (data structure or +operational similarity) and individual metric. In practice, the +two leading components are likely to be macros in the PMNS specification +source, and +.BR pmcpp (1) +will convert the macros to integers. These macros for +the initial components of the +.CW pmid +are likely to be defined either in +a standard include file, e.g. \c +.IR $PCP_VAR_DIR/pmns/stdpmid , +or in the current source file. +.PP +To support dynamic metrics, where the existence of a metric is known to +a PMDA, but not visible in the PMNS, a variant syntax for the +.CW pmid +is supported, namely a domain number followed by asterisks for the other +components of the +.CW pmid , +e.g. 14:*:*. +The corresponding metric name forms the root of a subtree of dynamic +metric names defined in the corresponding PMDA as identified by the domain +number. +.PP +The current allocation of the high-order (PMD or domain) component +of PMIDs is as follows. +.TS +box,center; +c | c +n | l. +Range Allocation +_ +0 reserved +_ +1-31 PMDAs from the PCP base product +_ +32-39 Oracle +_ +40-47 Sybase +_ +48-55 Informix +_ +56-58 SNMP Gateway PMDA +_ +59-63 Linux PMDAs +_ +64-69 ISV PMDAs +_ +70-128 more PMDAs from the PCP base product +_ +129-510 End-user PMDAs and demo PMDAs +_ +511 RESERVED +.TE +.SH EXAMPLE +.ft CW +.nf +#define KERNEL 1 +#define FOO 317 +root { + network + cpu + dynamic FOO:*:* +} + +#define NETWORK 26 +network { + intrate KERNEL:NETWORK:1 + packetrate +} + +network.packetrate { + in KERNEL:NETWORK:35 + out KERNEL:NETWORK:36 +} + +#define CPU 10 +cpu { + syscallrate KERNEL:CPU:10 + util +} + +#define USER 20 +#define SYSTEM 21 +#define IDLE 22 + +cpu.util { + user KERNEL:CPU:USER + sys KERNEL:CPU:SYSTEM + idle KERNEL:CPU:IDLE +} +.fi +.ft R +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmcpp (1), +.BR PCPIntro (3), +.BR PMAPI (3), +.BR pmErrStr (3), +.BR pmGetConfig (3), +.BR pmLoadASCIINameSpace (3), +.BR pmLoadNameSpace (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). |