pmns(5)
NAME
pmns - the performance metrics name space
SYNOPSIS
$PCP_VAR_DIR/pmns
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). A PMNS specifies the association between a metric's name and its PMID. A PMNS is defined on one or more ASCII source files. Loading of a PMNS is done by calling pmLoadNameSpace(3) or pmLoadASCIINameSpace(3). As of Version 3.10.3 of PCP, by default duplicate names for the same PMID are allowed in the PMNS, although pmLoadASCIINameSpace(3) provides an alternative interface with user-defined control over the processing of duplicate names in the PMNS. The external format for a PMNS conforms to the syntax and semantics described in the following sections. There is one default PMNS in the files below $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 $PCP_DEMOS_DIR/Tutorial. Although an application can call pmLoadNameSpace(3), normally this is only done directly for the -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 PCPIntro(1)), however, then the local PMNS will be loaded using the path specified by the environment variable PMNS_DEFAULT.
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.
PROCESSING FRAMEWORK
The PMNS specification is initially passed through pmcpp(1). This means the following facilities may be used in the specification + C-style comments + #include directives + #define directives and macro substitution + conditional processing via #ifdef ... #endif, etc. When pmcpp(1) is executed, the ``standard'' include directories are the current directory and $PCP_VAR_DIR/pmns. The pre-processing with pmcpp(1) may be omitted in some cases where the PMNS is known to not contain any C-style comments, preprocessor directives or macros. Refer to the descriptions of pmLoadASCIINameSpace(3) and pmLoadNameSpace(3) for details.
SYNTAX
The general syntax for a non-leaf node in the PMNS is as follows
pathname {
name [pmid]
...
}
Where 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.
Non-leaf nodes in the PMNS may be defined in any order.
The descendent nodes are defined by the set of names, relative to the
pathname of their parent non-leaf node. For the descendent nodes, leaf
nodes have a pmid specification, non-leaf nodes do not. The syntax for
the pmid specification has been chosen to help manage the allocation of
PMIDs across disjoint and autonomous domains of administration and
implementation. Each 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 pmcpp(1) will
convert the macros to integers. These macros for the initial
components of the pmid are likely to be defined either in a standard
include file, e.g. $PCP_VAR_DIR/pmns/stdpmid, or in the current source
file.
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 pmid is
supported, namely a domain number followed by asterisks for the other
components of the 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.
The current allocation of the high-order (PMD or domain) component of
PMIDs is as follows.
Range Allocation
0 reserved
1-384 production PMDAs from PCP packages
385-510 end-user PMDAs (allocate from high to low)
511 reserved for dynamic PMNS entries
EXAMPLE
#define KERNEL 1
#define FOO 387
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
}
SEE ALSO
PCPIntro(1), pmcd(1), pmcpp(1), PCPIntro(3), PMAPI(3), pmErrStr(3), pmGetConfig(3), pmLoadASCIINameSpace(3), pmLoadNameSpace(3), pcp.conf(5) and pcp.env(5).
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
