summaryrefslogtreecommitdiff
path: root/man/man5
diff options
context:
space:
mode:
Diffstat (limited to 'man/man5')
-rw-r--r--man/man5/GNUmakefile30
-rw-r--r--man/man5/mmv.5202
-rw-r--r--man/man5/pcp-archive.5348
-rw-r--r--man/man5/pcp.conf.5119
-rw-r--r--man/man5/pcp.env.561
-rw-r--r--man/man5/pmieconf.5308
-rw-r--r--man/man5/pmns.5252
-rw-r--r--man/man5/pmview.51036
8 files changed, 2356 insertions, 0 deletions
diff --git a/man/man5/GNUmakefile b/man/man5/GNUmakefile
new file mode 100644
index 0000000..4470193
--- /dev/null
+++ b/man/man5/GNUmakefile
@@ -0,0 +1,30 @@
+#
+# Copyright (c) 2014 Red Hat.
+# 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.
+#
+
+TOPDIR = ../..
+include $(TOPDIR)/src/include/builddefs
+-include ./GNUlocaldefs
+
+MAN_SECTION = 5
+MAN_PAGES = $(shell echo *.5)
+MAN_DEST = $(PCP_MAN_DIR)/man$(MAN_SECTION)
+LSRCFILES = $(MAN_PAGES)
+
+default_pcp default : $(MAN_PAGES)
+
+include $(BUILDRULES)
+
+install install_pcp : default
+ @$(INSTALL_MAN)
diff --git a/man/man5/mmv.5 b/man/man5/mmv.5
new file mode 100644
index 0000000..79e763c
--- /dev/null
+++ b/man/man5/mmv.5
@@ -0,0 +1,202 @@
+'\"! tbl | nroff \-man
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2009 Max Matveev
+.\" Copyright (c) 2009 Aconex. 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 MMV 5 "" "Performance Co-Pilot"
+.SH NAME
+\f3mmv\f1 \- Memory Mapped Values for Performance Co-Pilot
+.SH SYNOPSIS
+.I $PCP_TMP_DIR/mmv/<file>
+.SH DESCRIPTION
+The files in \f2$PCP_TMP_DIR/mmv\f1 are generated by
+\f2mmv_stats_init\f1() function from \f3libpcp_mmv\f1 library. There could
+be multiple files in this directory, each file representing a single source
+of the performance metrics. The metrics are harvested by the \f2mmv\f1 PMDA
+which exports them to the rest of the Performance Co-Pilot infrastructure.
+.SH FILE FORMAT
+Each file starts with the following header:
+.TS
+box,center;
+c | c | c
+n | n | l.
+Offset Length Name
+_
+0 4 tag == "MMV\\0"
+_
+4 4 Version
+_
+8 8 Generation 1
+_
+16 8 Generation 2
+_
+24 4 Number of TOC entries
+_
+28 4 Flags
+_
+32 4 Process identifier (PID)
+_
+36 4 Cluster identifier
+.TE
+.PP
+.PP
+The generation numbers are timestamps at the time of file
+creation, and must match for the file to be considered by
+the MMV PMDA.
+.PP
+The flags can specify ways in which the client would like
+the MMV PMDA to behave - e.g. the MMV_FLAG_PROCESS flag
+specifies that only if the process identified by PID is
+currently running should those values be exported.
+.PP
+Finally, if set, the cluster identifier is a hint to the MMV
+PMDA as to what cluster should be used with this application
+when forming the individual metric identifiers.
+A performance metric identifier (see \f2PMDA\f1(3)) consists of
+the PMDA domain number, the cluster number, and the individual
+item numbers described in the Metrics section.
+.PP
+The header is followed by at least 2 TOC sections:
+one section for metrics and another for values.
+The TOC section has the following format:
+.TS
+box,center;
+c | c | c
+n | n | l.
+Offset Length Value
+_
+0 4 Section Type (see \f2mmv_stats.h\f1)
+_
+4 4 Number of entries in the section
+_
+8 8 Section's offset from the start of the file
+.TE
+.PP
+.PP
+The section types are:
+.IP
+1:
+Indoms (instance domain definitions)
+.IP
+2:
+Instances
+.IP
+3:
+Metrics (metric definitions)
+.IP
+4:
+Values
+.IP
+5:
+String
+.PP
+The only mandatory sections are Metrics and Values.
+Indoms and Instances sections only appear if there are metrics with
+multiple instances.
+String sections only appear if there are metrics with string values,
+or when Metrics or Indoms are defined with help text.
+.PP
+The entries in the Indoms section have the following format:
+.TS
+box,center;
+c | c | c
+n | n | l.
+Offset Length Value
+_
+0 4 Unique serial number for this domain
+_
+4 4 Number of entries in the domain
+_
+8 8 Offset to first instance
+_
+16 8 Short help text offset
+_
+24 8 Long help text offset
+.TE
+.PP
+.PP
+The entries in the Instances section have the following format:
+.TS
+box,center;
+c | c | c
+n | n | l.
+Offset Length Value
+_
+0 8 Offset into the indom section
+_
+8 4 Unused padding (zero filled)
+_
+12 4 Internal instance identifier
+_
+16 64 External instance identifier
+.TE
+.PP
+.PP
+The entries in the Metrics section have the following format:
+.TS
+box,center;
+c | c | c
+n | n | l.
+Offset Length Value
+_
+0 64 Metric Name
+_
+64 4 Metric Item (see \f2PMDA\f1(3))
+_
+68 4 Metric Type (see \f2mmv_stats.h\f1)
+_
+72 4 Semantics (see \f2PMAPI\f1(3))
+_
+76 4 Dimensions (see \f2PMAPI\f1(3))
+_
+80 4 Instance Domain ID
+_
+84 4 Unused padding (zero filled)
+_
+88 8 Short help text offset
+_
+96 8 Long help text offset
+.TE
+.PP
+.PP
+The entries in the Values section have the following format:
+.TS
+box,center;
+c | c | c
+n | n | l.
+Offset Length Value
+_
+0 8 \f3pmAtomValue\f1 (see \f2PMAPI\f1(3))
+_
+8 8 Extra space for STRING and ELAPSED
+_
+16 8 Offset into the Metrics section
+_
+24 8 Offset into the Instances section
+.TE
+.PP
+.PP
+Each entry in the strings section is a 256 byte character array,
+containing a single NULL-terminated character string.
+So each string has a maximum length of 256 bytes, which includes
+the terminating NULL.
+.PP
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR PMAPI (3),
+.BR mmv_stats_init (3),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
diff --git a/man/man5/pcp-archive.5 b/man/man5/pcp-archive.5
new file mode 100644
index 0000000..f27547d
--- /dev/null
+++ b/man/man5/pcp-archive.5
@@ -0,0 +1,348 @@
+'\"! tbl | nroff \-man
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2014 Red Hat Inc.
+.\"
+.\" 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 PCP-ARCHIVE 5 "" "Performance Co-Pilot"
+
+.SH NAME
+\f3pcp-archive\f1 \- Archive Files for Performance Co-Pilot
+
+.SH SYNOPSIS
+
+.I $PCP_LOG_DIR/pmlogger/*/*.{meta,index,0}
+
+.I $PCP_LOG_DIR/pmmgr/*/*.{meta,index,0}
+
+.SH DESCRIPTION
+
+PCP log archives store volumes of historical values of arbitrary
+Performance Co-Pilot metrics recorded from a single host. Archives
+are self-contained in the sense that they contain all the important
+metadata that would be required for off-line or off-site analysis.
+The format is intended to be stable in order to allow long-term
+historical storage and processing by current tools. (Compatibility
+in the other direction \- new files, old tools \- is not as fully
+assured.)
+.PP
+Archives may be read by most PCP client tools, using the
+.IR "\-a ARCHIVE"
+option, or dumped raw by
+.BR pmdumplog (1).
+Archives may be created by
+.BR pmlogger (1)
+and bulk-import tools.
+Archives may be merged, analyzed, and subsampled using specialized
+tools such as
+.BR pmlogsummary "(1), " pmlogreduce "(1), " pmlogrewrite "(1), and " pmlogextract (1).
+In addition, PCP archives may be grouped together into PCP "archive folios",
+which are managed by the
+.BR pmafm (1)
+tool.
+.PP
+PCP archives consist of several physical files that share a common arbitrary prefix,
+e.g.,
+.IR myarchive .
+.TP
+myarchive.0, myarchive.1, ...
+Metric values. May grow rapidly.
+.TP
+myarchive.meta
+Information for PMAPI functions such as
+.IR pmLookupDesc "(3) and " pmGetInDom (3).
+May grow in fits and spurts, as logged instances and instance domains vary.
+.TP
+myarchive.index
+A temporal index, mapping timestamps to offsets in the other files.
+Grows slowly.
+
+.SH COMMON FEATURES
+
+All three types of files have a similar record-based structure, a
+convention of network-byte-order (big-endian) encoding, and 32-bit
+fields for tagging/padding for those records. Strings are stored as
+8-bit characters without assuming a specific encoding, so normally
+ASCII. See also the
+.BR __pmLog*
+types in
+.IR include/pcp/impl.h .
+
+.SS RECORD FRAMING
+.PP
+The volume and meta files are divided into self-identifying records.
+.TS
+box,center;
+c | c | c
+c | c | l.
+Offset Length Name
+_
+0 4 N, length of record, in bytes, including this field
+4 N-8 record payload, usually starting with a 32-bit tag
+N-4 4 N, length of record (again)
+.TE
+
+.SS ARCHIVE LOG LABEL
+All three types of files begin with a "log label" header, which
+identifies the host name, the time interval covered, and a time zone.
+.TS
+box,center;
+c | c | c
+c | c | l.
+Offset Length Name
+_
+0 4 tag, PM_LOG_MAGIC | PM_LOG_VERS02=0x50052602
+4 4 pid of pmlogger process that wrote file
+8 4 log start time, seconds part (past UNIX epoch)
+12 4 log start time, microseconds part
+16 4 current log volume number (or \-1=.meta, \-2=.index)
+20 64 name of collection host
+80 40 time zone string ($TZ environment variable)
+.TE
+.PP
+All fields, except for the current log volume number field, match for
+all archive-related files produced by a single run of the tool.
+
+.SH ARCHIVE VOLUME (.0, .1, ...) RECORDS
+
+.SS pmResult
+
+After the archive log label record, an archive volume file contains
+metric values corresponding to the
+.IR pmResult
+set of one
+.IR pmFetch
+operation, which is almost identical to the form on disk. The record
+size may vary according to number of PMIDs being fetched, the number
+of instances for their domains. File size is limited to 2GB, due to
+storage of 32-bit offsets within the .index file.
+.TS
+box,center;
+c | c | c
+c | c | l.
+Offset Length Name
+_
+0 4 timestamp, seconds part (past UNIX epoch)
+4 4 timestamp, microseconds part
+8 4 number of PMIDs with data following
+12 M pmValueSet #0
+12+M N pmValueSet #1
+12+M+N ... ...
+NOP X pmValueBlock #0
+NOP+X Y pmValueBlock #1
+NOP+X+Y ... ...
+.TE
+.PP
+Records with a number-of-PMIDs equal to zero are "markers", and may
+represent interruptions, missing data, or time discontinuities in
+logging.
+
+.SS pmValueSet
+
+This subrecord represents the measurements for one metric.
+
+.TS
+box,center;
+c | c | c
+c | c | l.
+Offset Length Name
+_
+0 4 PMID
+4 4 number of values
+8 4 storage mode, PM_VAL_INSITU=0 or PM_VAL_DPTR=1
+12 M pmValue #0
+12+M N pmValue #1
+12+M+N ... ...
+.TE
+
+.PP
+The metric-description metadata for PMIDs is found in the .meta files.
+These entries are not timestamped, so the metadata is assumed to be
+unchanging throughout the archiving session.
+
+.SS pmValue
+
+This subrecord represents one measurement for one instance of the metric.
+It is a variant type, depending on the parent pmValueSet's value-format
+field. This allows small numbers to be encoded compactly, but retain
+flexibility for larger or variable-length data to be stored later in the
+pmResult record.
+
+.TS
+box,center;
+c | c | c
+c | c | l.
+Offset Length Name
+_
+0 4 number in instance-domain (or PM_IN_NULL=-1)
+4 4 value (INSITU) \fIor\fR
+ offset in pmResult to our pmValueBlock (DPTR)
+.TE
+
+.PP
+The instance-domain metadata for PMIDs is found in the .meta files.
+Since the numeric mappings may change during the lifetime of the
+logging session, it is important to match up the timestamp of the
+measurement record with the corresponding instance-domain record.
+That is, the instance-domain corresponding to a measurement at time T
+are the records with largest timestamps T' <= T.
+
+.SS pmValueBlock
+
+Instances of this subrecord are placed at the end of the
+.IR pmValueSet ,
+after all the
+.IR pmValue
+subrecords. Iff needed, they are padded at the end to the next-higher
+32-bit boundary.
+
+.TS
+box,center;
+c | c | c
+c | c | l.
+Offset Length Name
+_
+0 1 value type (same as \fIpmDesc.type\fR)
+1 3 4 + N, the length of the subrecord
+4 N bytes that make up the raw value
+4+N 0-3 padding (not included in the 4+N length field)
+.TE
+
+Note that for
+.IR PM_TYPE_STRING ,
+the length includes an explicit NUL terminator byte.
+For
+.IR PM_TYPE_EVENT ,
+the value bytestring is further structured.
+
+.SS pmEventArray
+
+.IR (TBD)
+
+.SH METADATA FILE (.meta) RECORDS
+
+After the archive log label record, the metadata file contains
+interleaved metric-description and timestamped instance-domain
+descriptors. File size is limited to 2GB, due to storage of 32-bit
+offsets within the .index file. Unlike the archive volumes, these
+records are not forced to 32-bit alignment! See also
+.IR src/libpcp/src/logmeta.c .
+
+.SS pmDesc
+
+Instances of this record represent the metric description, giving a
+name, type, instance-domain identifier, and a set of names to each
+PMID used in the archive volume.
+
+.TS
+box,center;
+c | c | c
+c | c | l.
+Offset Length Name
+_
+0 4 tag, TYPE_DESC=1
+4 4 pmid
+8 4 type (PM_TYPE_*)
+12 4 instance domain number
+16 4 semantics of value (PM_SEM_*)
+20 4 units: bit-packed pmUnits
+4 4 number of alternative names for this PMID
+28 4 N: number of bytes in this name
+32 N bytes of the name, no NUL terminator nor padding
+32+N 4 N2: number of bytes in next name
+36+N N2 bytes of the name, no NUL terminator nor padding
+\... ... ...
+.TE
+
+.SS pmLogIndom
+
+Instances of this record represent the number-string mapping table of
+an instance domain. The instance domain number will have already been
+mentioned in a prior
+.IR pmDesc
+record. Since new instances may appear over a long archiving run, these
+records are timestamped, and must be searched when decoding
+.IR pmResult
+records from the main archive volumes. Instance names may be reused
+between instance numbers, so an offset-based string table is used that
+could permit sharing.
+
+.TS
+box,center;
+c | c | c
+c | c | l.
+Offset Length Name
+_
+0 4 tag, TYPE_INDOM=2
+4 4 timestamp, seconds part (past UNIX epoch)
+8 4 timestamp, microseconds part
+12 4 instance domain number
+16 4 N: number of instances in domain, normally >0
+20 4 first instance number
+24 4 first offset into string table (see below)
+28 4 second instance number (if appropriate)
+32 4 second offset into string table (etc.)
+\... ... ...
+20+8*N M base of string table, containing
+ packed, NUL-terminated instance names
+.TE
+.PP
+Records of this form \fIreplace\fR the existing instance-domain: prior
+records are not searched for resolving instance numbers in measurements
+after this timestamp.
+
+.SH INDEX FILE (.index) RECORDS
+
+After the archive log label record, the temporal index file contains a
+plainly concatenated, unframed group of tuples, which relate timestamps to
+32-bit seek offsets in the volume and meta files. (This limits those
+files to 2GB in size.) These records are fixed-size, fixed-format,
+and are \fInot\fR enclosed in the standard length/payload/length
+wrapper: they just take up the entire remainder of the .index file.
+See also
+.IR src/libpcp/src/logutil.c .
+
+.TS
+box,center;
+c | c | c
+c | c | l.
+Offset Length Name
+_
+0 4 event time, seconds part (past UNIX epoch)
+4 4 event time, microseconds part
+8 4 archive volume number (0...N)
+12 4 byte offset in .meta file of pmDesc or pmLogIndom
+16 4 byte offset in archive volume file of pmResult
+.TE
+
+Since temporal indexes are optional, and exist only to speed up
+time-wise random access of metrics and their metadata, index records
+are emitted only intermittently. An archive reader program should not
+presume any particular rate of data flow into the index. However,
+common events that may trigger a new temporal-index record include
+changes in instance-domains, switching over to a new archive volume,
+just starting or stopping logging. One reliable invariant however is
+that, for each index entry, there are to be no meta or archive-volume
+records with a timestamp after that in the index, but physically
+before the byte-offset in the index.
+
+.PP
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR PMAPI (3),
+.BR pmlogger (1),
+.BR pmdumplog (1),
+.BR pmafm (1),
+.BR pcp.conf (5),
+and
+.BR pcp.env (5).
diff --git a/man/man5/pcp.conf.5 b/man/man5/pcp.conf.5
new file mode 100644
index 0000000..be29c2d
--- /dev/null
+++ b/man/man5/pcp.conf.5
@@ -0,0 +1,119 @@
+'\"! 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 PCP.CONF 5 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pcp.conf\f1 \- the Performance Co-Pilot configuration and environment file
+.\" literals use .B or \f3
+.\" arguments use .I or \f2
+.SH SYNOPSIS
+.I /etc/pcp.conf
+.SH DESCRIPTION
+When using Performance Co-Pilot (PCP) tools and utilities
+and when calling PCP library functions, a standard set of
+environment variables are defined in
+.IR /etc/pcp.conf .
+These variables are generally used to specify the location of
+various PCP pieces in the file system and may be loaded into
+shell scripts by sourcing the
+.IR /etc/pcp.env (5)
+shell script and queried by C/C++ programs using the
+.IR pmGetConfig (3)
+library function.
+If a variable is already defined in the environment,
+the values in
+.I pcp.conf
+do
+.B not
+override those values, i.e. the values in
+.I pcp.conf
+serve as installation defaults only.
+.PP
+Both the
+.I pcp.env
+and
+.I pcp.conf
+files are expected to be found in
+.I /etc
+by default.
+If required, the
+.I pcp.conf
+file may be relocated and
+.B PCP_CONF
+set in the environment to specify the full path to the new location.
+The
+.I pcp.env
+file can not be relocated (this is the only hard coded path
+required by PCP).
+.PP
+The syntax rules for
+.I pcp.conf
+are as follows :
+.IP 1. 4
+the general syntax is
+.br
+.ce 1
+.B "PCP_VARIABLE_NAME=variable value to end of line"
+.IP 2. 4
+lines that begin with
+.B #
+and all blank lines are ignored.
+.IP 3. 4
+all variables must be prefixed with
+.BR PCP_ .
+This is a security issue - variables that do not have this prefix will
+be silently ignored.
+.IP 4. 4
+there should be no space between the variable name and the literal
+.B =
+and no space between the
+.B =
+and the variable value (unless the value actually starts with a space).
+This is required because the
+.I pcp.conf
+file may be sourced directly by Makefiles as well as interpreted by the
+.I pcp.env
+script and the
+.I "pmGetConfig"
+function.
+.IP 5. 4
+variable values may contain spaces and should
+.B not
+be quoted.
+The
+.I pcp.env
+script automatically quotes all variable values from the character
+immediately following the
+.B =
+through to the end of the line.
+.PP
+For further details and an explanation of the use of
+each variable, see the comments in the
+.I /etc/pcp.conf
+file itself.
+.SH ENVIRONMENT
+The
+.B PCP_CONF
+environment variable specifies an alternative path to the
+.I pcp.conf
+file.
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR PCPIntro (3),
+.BR PMAPI (3),
+.BR pmGetConfig (3)
+and
+.BR pcp.env (5).
diff --git a/man/man5/pcp.env.5 b/man/man5/pcp.env.5
new file mode 100644
index 0000000..edd90d4
--- /dev/null
+++ b/man/man5/pcp.env.5
@@ -0,0 +1,61 @@
+'\"! 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 PCP.ENV 5 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pcp.env\f1 \- script to set Performance Co-Pilot run-time environment variables
+.\" literals use .B or \f3
+.\" arguments use .I or \f2
+.SH SYNOPSIS
+.I /etc/pcp.env
+.SH DESCRIPTION
+The
+.I pcp.env
+script is sourced by assorted Performance Co-Pilot (PCP) scripts
+and utilities to define the PCP operating environment variables.
+The conjugate for executable programs using the PCP libraries is the
+.IR __pmGetConfig (3)
+function.
+.PP
+Typical usage of
+.I pcp.env
+in a script is as follows :
+.IP
+ #! /bin/sh
+
+ # source the PCP environment variables
+ . /etc/pcp.env
+ rest of script ...
+
+.PP
+The full syntax and semantics of the
+.I pcp.conf
+file and the
+.I __pmGetConfig
+function are described in their respective reference pages.
+.SH ENVIRONMENT
+The
+.B PCP_CONF
+environment variable specifies an alternative path to the
+.I pcp.conf
+file.
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR PCPIntro (3),
+.BR PMAPI (3),
+.BR __pmGetConfig (3)
+and
+.BR pcp.conf (5).
diff --git a/man/man5/pmieconf.5 b/man/man5/pmieconf.5
new file mode 100644
index 0000000..5314463
--- /dev/null
+++ b/man/man5/pmieconf.5
@@ -0,0 +1,308 @@
+'\"macro stdmacro
+.ie \(.g \{\
+.\" ... groff (hack for khelpcenter, man2html, etc.)
+.TH PMIECONF 5 "PCP" "Performance Co-Pilot"
+\}
+.el \{\
+.if \nX=0 .ds x} PMIECONF 5 "PCP" "Performance Co-Pilot"
+.if \nX=1 .ds x} PMIECONF 5 "Performance Co-Pilot"
+.if \nX=2 .ds x} PMIECONF 5 "" "\&"
+.if \nX=3 .ds x} PMIECONF "" "" "\&"
+.TH \*(x}
+.rr X
+\}
+.SH NAME
+pmieconf \- generalized pmie rules and customizations
+.SH DESCRIPTION
+The pmieconf file formats are used by the
+.BR pmieconf (1)
+tool as a way to generalize
+.BR pmie (1)
+rule sets such that they can be easily configured for different systems and
+different environments.
+There are two completely different (although closely related) file formats
+discussed here, namely ``pmieconf-rules'' and ``pmieconf-pmie''.
+.PP
+The directory
+.B $PCP_VAR_DIR/config/pmieconf
+contains information about all the default system
+.B pmie
+generalized rules and variables, including default values for all variables.
+These files are in the pmieconf-rules format.
+Although new pmieconf-rules files can be added, the files in this directory
+should never be changed.
+Instead, use the
+.B pmieconf
+utility to change variable values in the
+.B pmie
+configuration file.
+.PP
+The pmieconf-pmie format allows site specific customizations of the rules
+contained in pmieconf-rules files and their associated variables.
+The pmieconf-pmie format is generated by
+.B pmieconf
+and should not be edited by hand.
+This generated file is in the
+.B pmie
+format, with some additional information held at the head of the file \- thus,
+the pmieconf-pmie format is a superset of the
+.B pmie
+file format (extended to hold customizations to the generalized rules, but
+also containing the actual performance rules for
+.B pmie
+to evaluate) which can also be parsed by
+.B pmie
+(all extensions are hidden within comments, and are thus meaningless to
+.B pmie
+itself).
+.PP
+The file
+.B $PCP_VAR_DIR/config/pmieconf/config.pmie
+contains local system settings for
+.B pmieconf
+configurable variables.
+The variable settings in this file replace the default values specified in
+.BR $PCP_VAR_DIR/config/pmieconf/*/* .
+.SH PMIECONF-PMIE SYNTAX
+All rule customization lines in a valid pmieconf-pmie specification
+are prefixed by ``//'' and are located at the head of the file \-
+this allows files containing a pmieconf-pmie specification to be
+successfully parsed by
+.BR pmie .
+A pmieconf-pmie must always have the first line in the form:
+.sp
+.nf
+ // pmieconf-pmie \f2version\f1 \f2pmieconf_path\f1
+.fi
+.sp
+The
+.I version
+specifies which version of the pmieconf-pmie syntax should be used to
+parse this file.
+Currently the only supported version is 1. The
+.I pmieconf_path
+specifies the path to the pmieconf-rules files which were used, by
+.BR pmieconf ,
+to generate this file. This is discussed in the
+.BR pmieconf (1)
+man page (see the
+.B \-r
+option).
+.PP
+The remainder of the specification consists of one line entries for each
+of the modified variables. The syntax for each line is:
+.sp
+.nf
+ // \f2rule_version\f1 \f2rule_name\f1 \f2rule_variable\f1 = \f2value\f1
+.fi
+.sp
+The
+.I rule_version
+and
+.I rule_name
+are used to identify the rule with which to associate the customization.
+These are followed by the
+.I rule_variable
+name (i.e. the variable of rule
+.I rule_name
+which has been changed)
+for which the new
+.I value
+is to be used.
+.PP
+A pmieconf-pmie specification must be terminated with the ``end'' keyword.
+This is used by
+.B pmieconf
+to distinguish where the customizations ends, and the actual
+.B pmie
+rule component begins.
+.SH PMIECONF-PMIE EXAMPLE
+The following example is a valid pmieconf-pmie format file, as generated by
+.BR pmieconf .
+In order to make changes by hand which are preserved by
+.BR pmieconf ,
+see the comments contained in the generated file (below) as to where such
+changes should be made.
+.sp
+.nf
+ // pmieconf-pmie 1 $PCP_VAR_DIR/config/pmieconf
+ // 1 memory.exhausted delta = "4 minutes"
+ // 1 memory.exhausted enabled = yes
+ // 1 memory.exhausted pcplog_action = yes
+ // end
+ //
+ // --- START GENERATED SECTION (do not change this section) ---
+ // generated by pmieconf on: [DATESTAMP]
+ //
+
+ // 1 memory.exhausted
+ delta = 4 minutes;
+ some_host (
+ ( avg_sample (swap.pagesout @0..9 ) ) > 0 &&
+ 30 %_sample swap.pagesout >= 5
+ ) -> shell 10 min "$PCP_BINADM_DIR/pmpost Severe demand for real memory" \\
+ " %vpgsout/s@%h";
+
+ // --- END GENERATED SECTION (changes below will be preserved) ---
+.fi
+.sp
+.PP
+To see how this all works, you can generate this file as follows:
+.sp
+.nf
+ # cat \- | pmieconf \-f /tmp/pmieconf.out \\
+ \-r $PCP_VAR_DIR/config/pmieconf/memory:$PCP_VAR_DIR/config/pmieconf/global
+ modify memory.exhausted delta "4 minutes"
+ modify memory.exhausted enabled yes
+ modify memory.exhausted pcplog_action yes
+ ^D
+ #
+.fi
+.sp
+Then verify that the generated file is a valid
+.B pmie
+configuration file using:
+.sp
+.nf
+ # pmie \-C /tmp/pmieconf.out
+.fi
+.sp
+This parses the file, and then exits after reporting any syntax errors.
+Now replace \-C with \-v (above), and watch
+.B pmie
+do its work!
+.SH PMIECONF-RULES SYNTAX
+A pmieconf-rules specification consists of a number of separate data objects
+which together form a complete rule specification (note that a specification
+may span multiple files and even multiple subdirectories).
+Each object must have an
+.I identifier
+string and a data
+.IR type ,
+followed by an (optional) list of
+.IR attribute s.
+.PP
+The generic specification of a pmieconf-rules object is thus:
+.sp
+.nf
+ \f2type\f1 \f2identifier\f1 [ \f2attribute\f1 = \f2value\f1 ]* ;
+.fi
+.sp
+The set of valid
+.IR type s
+is: "rule" (rule definition), "string" (arbitrary, double-quote enclosed
+string), "double", "integer", "unsigned", "percent" (real number between 0
+and 100), "hostlist" (space separated list of host names), "instlist" (space
+separated list of metric instance names), and the four
+.B pmie
+action types, namely
+"print", "shell", "alarm", and "syslog".
+.PP
+Rule names use the ``.'' character to introduce the concept of a rule group,
+e.g. "memory.exhausted" associates this rule with the "memory" group.
+.B pmieconf
+can operate at either the level of rule groups or individual rules.
+The group name "global" is reserved and may not be used with any rule.
+.PP
+Usually when an object is created it is associated with the current rule.
+However, if an object's name is preceded by the reserved group name "global",
+then that object is visible to all rules.
+.PP
+The set of valid
+.IR attribute s
+is: "help" (descriptive text about this object), "modify" (\f2value\f1 is
+yes/no, flags whether
+.B pmieconf
+should allow changes), "enabled" (\f2value\f1 is yes/no, flags whether this is
+on or off - only meaningful for rules and actions), "display" (yes/no - flags
+whether
+.B pmieconf
+should show this object), "default" (\f2value\f1 determined by \f2type\f1, and
+is the default value for this object), and specific to objects of rule type
+are the "version", "predicate", and "enumerate" attributes. "version" and
+"predicate" are fairly self explanatory ("predicate" must equate to a valid
+.B pmie
+rule when expanded), but "enumerate" requires further discussion.
+.PP
+The "enumerate" clause is useful when you wish to generate multiple, similar
+.B pmie
+rules from a single predicate.
+This is most useful for rule definitions wishing to use the "some_inst"
+clause in the
+.B pmie
+language across multiple hosts.
+For a rule to use these together, it must be certain that the
+instance list is the same on all of the monitored hosts.
+This is rarely true, so the "enumerate" attribute allows us to generate
+multiple rules, expanded over variables of either type "instlist" or "hostlist".
+These variables make up the value for the "enumerate" attribute \- which is
+a space-separated list of "instlist" or "hostlist" variable names.
+.PP
+Objects can be incorporated into other object definitions using the
+$\f2identifier\f1$ syntax. See the example later for more insight into
+how this is useful.
+.PP
+When
+.B pmieconf
+is generating the
+.B pmie
+configuration file, it looks at each enabled rule with N enabled
+actions (where N > 0) and expands the string:
+.sp
+.nf
+ // "version" \f2identifier\f1
+ delta = $delta$;
+ "predicate" -> $threshold$ $action1$ & ... & $actionN$ ;
+.fi
+.sp
+The delta, threshold, and action variables are defined globally
+(using the "global" keyword) for all rules, but can, of course,
+be changed at the level of an individual rule or rule group.
+.SH PMIECONF-RULES EXAMPLE
+The following is an example of a single pmieconf-rules specification,
+showing a number of different aspects of the language discussed above.
+The example defines a rule ("memory.exhausted") and a string ("rule").
+.sp
+.nf
+ rule memory.exhausted
+ default = "$rule$"
+ predicate =
+ "some_host (
+ ( avg_sample (swap.pagesout $hosts$ @0..9 ) ) > 0 &&
+ $pct$ %_sample swap.pagesout $hosts$ @0..9 >= $threshold$
+ )"
+ enabled = yes
+ version = 1
+ help =
+ "The system is swapping modified pages out of main memory to the
+ swap partitions, and has been doing this on at least pct of the
+ last 10 evaluations of this rule.
+ There appears to be insufficient main memory to meet the resident
+ demands of the current workload.";
+
+ string rule
+ default = "Severe demand for real memory"
+ modify = no
+ display = no;
+.fi
+.sp
+Note that for the above rule to be complete, "threshold" and "pct" would
+also need to be defined - for the full expression of this rule, refer to
+.IR $PCP_VAR_DIR/config/pmieconf/memory/exhausted .
+.PP
+.SH FILES
+.PD 0
+.TP 10
+.IR $PCP_VAR_DIR/config/pmieconf/ */*
+generalized system resource monitoring rules
+.TP 10
+.I $PCP_VAR_DIR/config/pmieconf/config.pmie
+default super-user settings for system resource monitoring rules
+.TP 10
+.I $HOME/.pcp/pmie/config.pmie
+default user settings for system resource monitoring rules
+.PD
+.SH SEE ALSO
+.BR pmie (1)
+and
+.BR pmieconf (1).
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).
diff --git a/man/man5/pmview.5 b/man/man5/pmview.5
new file mode 100644
index 0000000..f60bfec
--- /dev/null
+++ b/man/man5/pmview.5
@@ -0,0 +1,1036 @@
+.TH PMVIEW 5 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmview\f1 \- configuration file format for performance
+.SH DESCRIPTION
+This man page describes version 2.1 of the
+.B pmview
+configuration file format.
+.PP
+The configuration format supports metrics from multiple hosts or archives. A
+configuration file can specify metrics without a source, with different hosts
+and different archives. However, a configuration file that contains archives
+may only have one archive for anyone host. When in ``replay'' mode, any
+metrics with host specific sources require an archive to be specified for that
+host on the command line or as a source to a previous metric. The archive must
+be the same archive (based on a string comparison of the archive names) of any
+archives specified in the configuration file for the same host.
+.PP
+The time controls will list all hosts that are specified on the command line
+and the configuration file in the timezone listing (see
+.BR pmtime (1)).
+.PP
+The configuration file format is based on a two-dimensional grid which
+can contain a variety of bars, stacks, links, pipes, labels and other
+grids. The grids resize each column and row to match the size of the
+largest item in that column or row. A configuration file that
+contains only one object does not require a grid. The
+.B pmview
+configuration file starts with an identification header in the first
+non-comment line:
+.PP
+.in 1.0i
+.ft CW
+.nf
+pmview Version 2.1 \f2[command_line]\f1
+.fi
+.ft R
+.in
+.PP
+The optional
+.I command_line
+should be the command line with which the tool was launched, if the
+configuration file has been generated by another tool. This is useful for
+applications that are to be restarted automatically on the next login, after
+the user has logged out while
+.B pmview
+was still running.
+Care should be taken to ensure that the command specified is either a
+full pathname or will be found on the PATH available at login.
+.PP
+All lines which begin with ``#'' are treated as comments and
+ignored. Otherwise, all spaces, tabs and newlines are treated as white space
+so multiple commands may be on the same line.
+.PP
+The syntax for specifying values in the configuration file is consistent for
+all commands, namely:
+.TP 4n
+.I color
+A color must be either a
+.BR X (1)
+color name, a
+.BR X (1)
+numerical color, or three normalized
+.I real
+values representing the saturation of red, green and blue. For example,
+the following colors are identical:
+.PP
+.in 1.5i
+.ft CW
+.nf
+red
+rgbi:1.0/0.0/0.0
+1.0 0.0 0.0
+.fi
+.ft R
+.in
+.TP 4n
+.I int
+An integer.
+.TP 4n
+.I metric
+A metric consists of an optional source (host or archive), the metric name,
+an optional instance list immediately after name, followed by the maximum (or
+normalization value). A colon (``:'') is used to separate a host name from the
+metric, and a forward slash (``/'') to separate an archive name from the
+metric. Instances are enclosed in square brackets and comma separated. Each
+instance may be enclosed in quotes.
+.IP
+For example, some legal metrics are:
+
+.in 1.5i
+.ft CW
+.nf
+kernel.all.cpu.idle 4000
+myhost:kernel.all.cpu.idle[cpu0,"cpu3"] 1000.0
+/path/to/myarchive/kernel.all.cpu.idle[cpu1] 1000
+.fi
+.ft R
+.in
+
+To assist the process of matching instance names, two further comparisons are
+made beyond a simple string comparison. If the instance name contains
+spaces, only the first word in the instance name is required to match the
+instance, assuming that the first word is unique. If the first word is not
+unique, only the first matching instance will be selected. The second
+comparison occurs if the first word is a number with leading zeros. Any
+leading zeros will be skipped before comparing the first word again. This
+permits process ids used in the
+.I proc
+metrics to be easily matched, without specifying the entire instance name. For
+example, to visualize the user and system time of
+.I init
+use the metric specification
+
+.in 1.5i
+.ft CW
+.nf
+proc.psusage.utime[1] 1000
+proc.psusage.stime[1] 1000
+.fi
+.ft R
+.in
+.TP 4n
+.I name
+A name for an object which may be referred to later in the configuration file.
+Names must be a single word consisting of all alphanumeric characters, as well
+as underscores, dashes and colons. It is recommended that names do not begin
+with an underscore as this may be interpreted as a keyword.
+.TP 4n
+.I pos
+This is the position of the object within the grid. The syntax of a position
+is:
+.IP
+.in 1.0i
+[ [\f2x\f1 \f2z\f1] [ [\f2width\f1 \f2depth\f1] [\f2alignment\f1] ] ]
+.in
+.TP 14
+.I " x"
+The horizontal coordinate (left to right) of the object, starting at 0. The
+default
+.I x
+is 0.
+.TP
+.I " z"
+The vertical coordinate (top to bottom) of the object, starting at 0. The
+default
+.I z
+is 0.
+.TP
+.I " width"
+The number of columns occupied by the object. The default
+.I width
+is 1.
+.TP
+.I " depth"
+The number of rows occupied by the object. The default
+.I depth
+is 1.
+.TP
+.I " alignment"
+The edge or corner that the object is aligned with. Possible alignments
+include: \f2north\f1, \f2south\f1, \f2east\f1, \f2west\f1, \f2northeast\f1,
+\f2northwest\f1, \f2southeast\f1, \f2southwest\f1 and \f2center\f1.
+Abbreviations like \f2se\f1 and \f2SE\f1 are also accepted. The default
+alignment is \f2center\f1.
+.IP
+The size of an object may not be known as the number of instances for some
+metrics will vary between hosts and
+PMDA
+configurations. Therefore, the position of the object can be used to specify
+the likely size of the object, so that the position of the surrounding objects
+is appropriately adjusted.
+.IP
+The following are legal positions:
+.TP 21
+.ft CW
+ 0 5
+.ft R
+The object is centered at grid position 0,5 occupying 1 grid square.
+.TP
+.ft CW
+ 1 2 north
+.ft R
+The object is aligned with the north edge of position 1,2 occupying 1 grid
+square.
+.TP
+.ft CW
+ 2 2 2 1 east
+.ft R
+The object is aligned to the eastern edge of position 3,2 and occupies 2 grid
+squares (2,2 and 3,2).
+.TP 4n
+.I string
+A string is a series of characters enclosed in double quotes. A string may
+not contain newlines or escaped double quotes.
+
+.PP
+There are several parameters that may affect the size, shape and color of
+objects when they are displayed. These parameters are scoped so that they only
+alter objects defined later in the same scope. Therefore, parameter settings
+at the top of a configuration file affect the entire scene, unless they are
+changed later in the file. Most of these parameters are also resources.
+.TP 4n
+\f3_barLength\f1 \f2int\f1
+The side length of the
+.B _bar
+and
+.B _stack
+blocks. Default is 28.
+.TP 4n
+\f3_barHeight\f1 \f2int\f1
+The maximum height of a
+.B _bar
+and
+.B _stack
+blocks. Default is 80.
+.TP 4n
+\f3_baseColor\f1 \f2color\f1
+The color of
+.BR _bar ,
+.B _grid
+and
+.B _stack
+base planes. Default is rgbi:0.15/0.15/0.15.
+.TP 4n
+\f3_baseHeight\f1 \f2int\f1
+The height of
+.BR _bar ,
+.B _grid
+and
+.B _stack
+base planes. Default is 2.
+.TP 4n
+\f3_gapWidth\f1 \f2int\f1
+The gap between blocks in a
+.B _bar
+object in the X-axis. The default is 8.
+.TP 4n
+\f3_gapDepth\f1 \f2int\f1
+The gap between blocks in a
+.B _bar
+object in the Z-axis. The default is 8.
+.TP 4n
+\f3_gapLabel\f1 \f2int\f1
+The gap between the base of a
+.B _bar
+object, and any metric or instance labels. The default is 6.
+.TP 4n
+\f3_gridWidth\f1 \f2int\f1
+The minimum width of a
+.B _grid
+column. The default is 20.
+.TP 4n
+\f3_gridDepth\f1 \f2int\f1
+The minimum depth of a
+.B _grid
+row. The default is 20.
+.TP 4n
+\f3_labelMargin\f1 \f2int\f1
+The margin around a
+.B _label
+object. The default is 5.
+.TP 4n
+\f3_labelColor\f1 \f2color\f1
+The color of
+.B _label
+and
+.B _bar
+labels. The default is white.
+.TP 4n
+\f3_marginWidth\f1 \f2int\f1
+The extra width of a
+.BR _bar ,
+.B _grid
+and
+.B _stack
+base plane beyond the objects on the plane. The default is 8.
+.TP 4n
+\f3_marginDepth\f1 \f2int\f1
+The extra depth of a
+.BR _bar ,
+.B _grid
+and
+.B _stack
+base plane beyond the objects on the plane. The default is 8.
+.TP 4n
+\f3_pipeLength\f1 \f2int\f1
+Total length of a
+.BR _pipe.
+The default is the value of
+.BR _barHeight.
+.TP 4n
+\f3_scale\f1 \f2real\f1
+The scale applied to the entire scene. This parameter may not be used within
+any objects, only at the top of the configuration file. The default is 1.0.
+.PP
+To simplify the specification of colors, a
+.B _colorList
+and a
+.B _colorScale
+may be used to define colors for an object which has metrics
+associated with it, i.e.
+.BR _bar ,
+.B _stack
+or
+.BR _pipe .
+A color list may be defined within an object, or named and defined at
+the top of a configuration file. A named color list may then be referenced
+within multiple objects:
+.TP 4n
+\f3_colorList\f1 \f2name\f1 \f3(\f1 \f2color\f1 [\f2color\f1...] \f3)\f1
+Associate the
+.IR color s
+with the color list
+.IR name .
+The assignment of colors to blocks depends on the type of an
+object. For example, the color list called
+.I foo
+has the same color three times:
+
+.RS 4
+.ft CW
+.nf
+_colorList foo ( red rgbi:1.0/0.0/0.0 1.0 0.0 0.0 )
+.fi
+.ft R
+.RE
+
+.TP 4n
+\f3_colorScale\f1 \f2name\f1 \f2color\f1 \f3(\f1 \f2color\f1 \f2real\f1 [\f2color\f1 \f2real\f1...] \f3)\f1
+Associate the
+.IR color s
+and
+.IR real s
+with the color list
+.IR name .
+The initial
+.I color
+is the default color of the object. The object will change color to the other
+colors when the normalized value of the object is equal to or greater than
+each
+.IR real .
+Therefore, each
+.I real
+must be larger than the previous
+.IR real ,
+and should be in the range 0.0 to 1.0. This scale gradually changes from blue
+to red:
+.PP
+.RS 4
+.ft CW
+.nf
+_colorScale coldToHot blue ( rgbi:0.5/0.0/1.0 0.3
+ purple 0.6
+ rgbi:1.0/0.0/0.5 0.8
+ red 0.95)
+.fi
+.ft R
+.RE
+.PP
+There are several different object types which could be found in a
+.B pmview
+scene:
+.BR _bar ,
+.BR _stack ,
+.BR _pipe ,
+.BR _grid ,
+.BR _link ,
+and
+.BR _label .
+There is also
+.B _xing
+which is a special type of the
+.BR _link .
+The
+.BR _bar ,
+.B _stack
+and
+.B _pipe
+objects are modulated by metric values, a
+.B _label
+is fixed text,
+.B _link
+and
+.B _xing
+are interconnects and a
+.B _grid
+is a container of objects, including other
+.B _grid
+objects, which controls the layout of the scene. A
+.B _grid
+object is only required if there are two or more objects in the scene.
+.PP
+.BR _bar ,
+.B _grid
+and
+.B _stack
+objects may have base planes which provide a point of reference for the blocks
+as they change height. A label can be applied to the base plane
+.B _grid
+object if it is
+.B _shown
+with:
+
+.in 1.5i
+.ft CW
+.nf
+\f3_baseLabel\f1 \f2name\f1|\f2string\f1
+.fi
+.ft R
+.in
+
+.B _baseLabel
+should be used within the scope of the relevant
+.BR _bar ,
+.B _grid
+or
+.B _stack
+object. The first ``\\n'' characters in the string will be replaced by a new
+line. Subsequent ``\\n'' characters will be ignored.
+.PP
+For a scene to be valid it must contain at least one modulated object.
+.PP
+The objects are defined as:
+.TP 4n
+\f3_bar\f1 [\f2options\f1] \f3(\f1 [\f2metric-list\f1] [\f2color-list\f1] [\f2label-list\f1] \f3)\f1
+A
+.B _bar
+object represents a collection of blocks. The number of blocks depends on the
+number of metrics and metric instances assigned to the object. By default, the
+blocks are modulated by changing the height of each block. Alternatively,
+blocks may be modulated by changing color, or both height and color. Each
+color in the
+.I color-list
+is assigned to each metric. Therefore, multiple instances of the one metric
+will have the same color. The
+.I options
+that may be passed to a
+.B _bar
+object are:
+.RS 4n
+.TP 4n
+.I pos
+The position of the
+.B _bar
+object within the current
+.B _grid
+object.
+.TP 4n
+\f3_col\f1|\f3_row\f1
+Position the blocks so that each instance is in a column
+.RB ( _col )
+or a row
+.RB ( _row ).
+This implies that each different metric is in a separate row or column,
+respectively. The default is
+.BR _col .
+.TP 4n
+\f3_show\f1|\f3_hide\f1
+Is the base plane visible? Default is
+.BR _show .
+.TP 4n
+\f3_ymod\f1|\f3_colormod\f1|\f3_colorymod\f1
+Modulate the blocks by adjusting their height
+.RB ( _ymod ),
+color
+.RB ( _colormod )
+or both height and color
+.RB ( _colorymod ).
+.TP 4n
+\f3_cube\f1|\f3_cylinder\f1
+Set the shape of the blocks. The default is
+.BR _cube .
+.RE
+.RS 4n
+.TP 4n
+\f3_groupbymetric\f1|\f3_groupbyinst\f1|\f3_groupbyrow|\f1|\f3groupbycol\f1
+Set the grouping of blocks when launching other tools. For tools like
+.BR pmchart (1)
+some views may generate many small charts which cannot be drawn entirely within
+the screen. Another problem is it may be more appropriate to generate charts
+with the same instance in each chart, rather then the same metric. The group
+specifiers control the algorithm used so that a separate chart will be drawn
+for each
+.B _metrics
+specification
+.RB ( _groupbymetric ),
+for the first, second etc. instance of each
+.B _metric
+.RB ( _groupbyinst ),
+or by the rows and columns of the
+.B _bar
+object depending on
+.B _row
+or
+.BR _col .
+The default is
+.BR _groupbymetric .
+.PP
+The options must be specified in this order, although preceding options are
+not required. Therefore, this is legal:
+
+.in 1.5i
+.ft CW
+.nf
+_bar _hide _cylinder ( ... )
+.fi
+.ft R
+.in
+
+The metrics, colors and labels are specified within the brackets in any order.
+Only the
+.I metric-list
+is mandatory.
+.TP 4n
+.I metric-list
+A
+.B _bar
+metric list contains a list of metric names, normalization values and an
+optional label for the metric:
+
+.RS 4n
+.ft CW
+.nf
+\f3_metrics\f1 \f3(\f1 \f2metric\f1 \f2real\f1 [\f2string\f1] [\f2metric\f1 \f2real\f1 [\f2string\f1]...] \f3)\f1
+.fi
+.ft R
+.RE
+
+.TP 4n
+.I color-list
+A
+.B _bar
+color list may be a named color list that was defined earlier, or an unnamed
+color list. A
+.B _colorScale
+list should be used when using
+.B _colormod
+or
+.B _colorymod
+modulation. Therefore, the syntax for color lists within a
+.B _bar
+object are any of:
+
+.RS 4n
+.ft CW
+.nf
+\f3_colorList\f1 \f2name\f1
+\f3_colorList\f1 \f3(\f1 \f2color\f1 [\f2color\f1...] \f3)\f1
+\f3_colorScale\f1 \f2name\f1
+\f3_colorScale \f2color\f1 \f3(\f1 \f2color\f1 \f2real\f1 [\f2color\f1 \f2real\f1...] \f3)\f1
+.fi
+.ft R
+.RE
+.TP 4n
+.I label-list
+In addition to labels for each metric in the
+.IR metric-list ,
+metric and instance labels may be defined using
+.B _metriclabels
+and
+.B _instlabels
+statements. The position of the labels around the
+.B _bar
+object depends on the
+.B _row
+or
+.B _col
+orientation of metrics and instances, and whether the label is read
+.B _towards
+the
+.B _bar
+object, or
+.BR _away .
+The default is
+.BR _towards .
+
+.RS 4
+.ft CW
+.nf
+\f3_metriclabels\f1 [\f3_away\f1|\f3_towards\f1] \f3(\f1 \f2name\f1|\f2string\f1 [\f2name\f1|\f2string\f1...] \f3)\f1
+\f3_instlabels\f1 [\f3_away\f1|\f3_towards\f1] \f3(\f1 \f2name\f1|\f2string\f1
+[\f2name\f1|\f2string\f1...] \f3)\f1
+.fi
+.ft R
+.RE
+
+.RE
+.TP 4n
+\f3_grid\f1 [\f2pos\f1] [\f3_show\f1|\f3_hide\f1] \f3(\f1 \f2objects\f1 \f3)\f1
+A
+.B _grid
+object is a container for objects, including other
+.B _grid
+objects.
+The rows and columns of a
+.B _grid
+object are resized to the largest object in the row or column. If an object
+spans multiple rows and/or columns, those rows and columns may be partly
+resized to contain the object. However, the resizing of rows and columns for
+objects occupying multiple rows and columns occurs after resizing for objects
+occupying only one grid square.
+
+A collision between objects occupying the same squares will be reported as an
+error message and the later object will be ignored.
+
+The options to a
+.B _grid
+object control the position
+.RI ( pos )
+of the
+.B _grid
+object in the parent
+.BR _grid ,
+and indicate whether to
+.B _show
+or
+.B _hide
+the
+.B _grid
+base plane. By default, the base plane is hidden.
+
+The parameters described above may be specified within the brackets of a
+.B _grid
+object, however they only apply to the objects within the
+.BR _grid ,
+not the
+.B _grid
+itself. For a parameter to be applied to a
+.B _grid
+object, it must be specified before the
+.B _grid
+object declaration.
+
+.RE
+.TP 4n
+.I "\f3_label\f1 [\f2options\f1] \f2string\f1"
+A
+.B _label
+object draws the contexts of
+.I string
+at the location, orientation and size specified in the
+.IR options :
+.RS 4n
+.TP 4n
+.I pos
+The position of the
+.B _label
+object
+in the current
+.B _grid
+object.
+.TP 4n
+\f3_left\f1|\f3_right\f1|\f3_up\f1|\f3_down\f1
+The orientation of the
+.IR string .
+The direction indicates the direction the label is read. Therefore,
+.B _right
+is the default since the string is read from left to right.
+.TP 4n
+\f3_small\f1|\f3_medium\f1|\f3_large\f1
+The font size. The default is
+.BR _medium .
+.RE
+
+.RE
+.TP 4n
+\f3_link\f1 \f2pos\f1 [\f2string\f1]
+A
+.B _link
+object draws a straight or L-shaped horizontal round ``pipe'' with
+diameter equal to 80% of the
+.I _baseHeight
+of an enclosing
+.BR _grid .
+The properties of the object are defined by the options:
+
+.RS 4n
+.TP 4n
+.I pos
+sets both the position of the
+.B _link
+on the grid and its shape.
+.B _link
+starts in the column and row on the
+.B _grid
+specified by first two numbers in the
+.I pos
+and spans the number of columns and rows set by the second two
+numbers. The
+.I alignment
+value is used to decide the orientation of the link (links are always
+aligned at the center):
+.I east
+and
+.I west
+links are straight and going from left to right,
+.I north
+and
+.I south
+links are straight and going from far end of the grid to near end,
+.I northeast,
+.I northwest,
+.I southeast
+and
+.I southwest
+links are L-shaped and connect the corresponding points of the compass,
+i.e. a
+.I northeast
+link takes on the general shape of the Latin letter ``L''.
+.TP 4n
+.I string
+sets the ``tag'' for the
+.B _link
+which will be displayed in the text window when the pointer is over the
+link.
+.RE
+
+
+.RE
+.TP 4n
+\f3_pipe\f1 \f2pos\f1 \f3(\f1 [\f2metric-list\f1] [\f2color-list\f1] [\f2tag\f1] \f3)\f1
+A
+.B _pipe
+object represent a set of cylinders, placed on top of each other and
+oriented parallel to the base plane. The diameter of a
+.B _pipe
+is equal to 80% of
+.IR _baseHeight .
+The number of blocks is dependent on the number of
+metric instances in the
+.IR metric-list .
+The colors in the
+.I color-list
+are assigned in turn to each cylinder in the
+.BR _pipe .
+The length of the
+.B _pipe
+is defined by the
+.IR _pipeLength .
+
+.RS 4n
+.TP 4n
+.I pos
+defines the position of the
+.B _pipe
+on the enclosing
+.B _grid
+and its orientation with
+.I alignment
+field used to define at which end of the pipe to stack the colored
+cylinders. The cylinders are stacked at the corresponding point of the
+compass and the pipe's direction is from the point of the compass
+towards the center of the compass. Only
+.IR east ,
+.IR west ,
+.IR north ,
+and
+.I south
+are valid values for the pipe's alignment.
+
+.RE
+The metrics, colors and label may be specified within the brackets in any
+order. Only the
+.I metric-list
+is mandatory.
+.TP 4n
+.I metric-list
+A
+.B _pipe
+metric list contains a list of metric names and normalization values:
+
+.RS 4n
+.ft CW
+.nf
+\f3_metrics\f1 \f3(\f1 \f2metric\f1 \f2real\f1 [\f2metric\f1 \f2real\f1...] \f3)\f1
+.fi
+.ft R
+.RE
+
+.TP 4n
+.I color-list
+A
+.B _pipe
+color list may be named color list that was defined earlier, or an unnamed
+color list:
+
+.RS 4n
+.ft CW
+.nf
+\f3_colorList\f1 \f2name\f1
+\f3_colorList\f1 \f3(\f1 \f2color\f1 [\f2color\f1...] \f3)\f1
+.fi
+.ft R
+.RE
+
+.TP 4n
+.I tag
+A
+.B _pipe
+may have a ``tag'' for the filler block (unanimated block on the
+``other'' end of the pipe) which will be displayed in the text window
+when the pointer is over that end of the pipe.
+
+.RS 4n
+.ft CW
+.nf
+\f3_pipeTag\f1 \f2name\f1|\f2string\f1
+.fi
+.ft R
+.RE
+
+.RE
+.TP 4n
+\f3_stack\f1 [\f2options\f1] \f3(\f1 [\f2metric-list\f1] [\f2color-list\f1] [\f2label\f1] \f3)\f1
+A
+.B _stack
+object represents a set of blocks placed vertically on top of each other. The
+number of blocks is dependent on the number of metric instances in the
+.IR metric-list .
+The colors in the
+.I color-list
+are assigned to each block in the
+.BR _stack .
+By default, the height of the
+.B _stack
+will be the sum of the height of each block. The
+.I options
+that may be passed to a
+.B _stack
+object are:
+.RS 4n
+.TP 4n
+.I pos
+The position of the
+.B _stack
+object within the current
+.B _grid
+object.
+.TP 4n
+\f3_show\f1|\f3_hide\f1
+Is the base plane visible? Default is
+.BR _show .
+.TP 4n
+\f3_utilmod\f1|\f3_fillmod\f1
+Force the height of the stack to always be the maximum height. This is achieved
+by normalizing the height of each block
+.RB ( _utilmod ),
+or by adding a grey block to the top of the stack
+.RB ( _fillmod ).
+.TP 4n
+\f3_cube\f1|\f3_cylinder\f1
+Set the shape of the blocks. The default is
+.BR _cube .
+.RE
+.RS 4n
+.PP
+The options must be specified in this order, although preceding options are
+not required. Therefore, this is legal:
+
+.in 1.5i
+.ft CW
+.nf
+_stack 1 1 _north _utilmod ( ... )
+.fi
+.ft R
+.in
+
+The metrics, colors and label may be specified within the brackets in any
+order. Only the
+.I metric-list
+is mandatory.
+.TP 4n
+.I metric-list
+A
+.B _stack
+metric list contains a list of metric names and normalization values:
+
+.RS 4n
+.ft CW
+.nf
+\f3_metrics\f1 \f3(\f1 \f2metric\f1 \f2real\f1 [\f2metric\f1 \f2real\f1...] \f3)\f1
+.fi
+.ft R
+.RE
+
+.TP 4n
+.I color-list
+A
+.B _stack
+color list may be named color list that was defined earlier, or an unnamed
+color list:
+
+.RS 4n
+.ft CW
+.nf
+\f3_colorList\f1 \f2name\f1
+\f3_colorList\f1 \f3(\f1 \f2color\f1 [\f2color\f1...] \f3)\f1
+.fi
+.ft R
+.RE
+
+.TP 4n
+.I label
+A
+.B _fillmod
+type
+.B _stack
+may have a label for the filler block:
+
+.RS 4n
+.ft CW
+.nf
+\f3_stackLabel\f1 \f2name\f1|\f2string\f1
+.fi
+.ft R
+.RE
+
+.RE
+.TP 4n
+\f3_xing\f1 \f2col\f1 \f2row\f1 \f2columns\f1 \f2rows\f1 \f2dir1\f1 ... \f2dir4\f1
+A
+.B _xing
+is a special kind of link which is used to draw a pair of links which
+cross each other. To convey the visual impression that the links do
+not join, one of the links is drawn as a ``broken'' cylinder.
+.I col
+and
+.I row
+define the position on the enclosing grid.
+.I columns
+and
+.I rows
+define the size of the bounding box. The end points of the crossing
+cylinders are placed exactly in the center of the corner cells of the
+bounding box and four small cylinders or stubs are used to join the
+perimeter of the bounding box with the end points on the crossing
+cylinders. Four
+.I dir
+values define the orientation of the stubs, starting at the upper left
+corner of the
+.B _xing
+and proceeding clockwise, such that respective stubs are used to join
+the point of the compass with the center on the cell (see example).
+.RE
+.SH EXAMPLE
+This simple example illustrates the use of parameters and different object
+types:
+
+.in 1i
+.ft CW
+.nf
+pmview Version 2.1
+# Use a lighter grey for the base planes
+_baseColor rgbi:0.5/0.5/0.5
+
+# Define colors for CPU object
+_colorList cpu ( blue2 red2 yellow2 cyan2 green2 )
+
+# The top grid object, but hide it from view
+_grid _hide (
+
+# Show the current load in a bar object
+ _bar 0 0 (
+ _baseLabel "Load averages over a\\n1, 5 and 15 minute interval"
+ _metrics (
+ kernel.all.load[1] 1 "1"
+ kernel.all.load[5] 1 "5"
+ kernel.all.load[15] 1 "15"
+ )
+ _colorList ( blue blue blue )
+ )
+
+# Add a label below the load bars
+ _label 0 1 "Load"
+
+# Change the color of the base plane for later objects
+ _baseColor pink
+
+# Show the CPU usage over all CPUs in a utilization stack
+ _stack 2 0 _south _utilmod (
+ _baseLabel "CPU Utilization over all CPUs"
+ _metrics (
+ kernel.all.cpu.user 1000
+ kernel.all.cpu.sys 1000
+ kernel.all.cpu.intr 1000
+ kernel.all.cpu.wait.total 1000
+ kernel.all.cpu.idle 1000
+ )
+ _colorList cpu
+ )
+
+# Add a label below the CPU stack
+ _label 2 1 "CPU"
+
+# Create a separate grid for links and pipes
+ _marginWidth 1
+ _marginDepth 1
+ _gridSpace 12
+ _grid 0 3 5 4 _hide (
+ _pipeLength 12
+ _baseHeight 12
+
+ # Add a pipe and a link with western orientation
+ _pipe 0 0 west (
+ _pipeTag "West pipe"
+ _metrics (
+ kernel.all.cpu.user 1000
+ kernel.all.cpu.sys 1000
+ kernel.all.cpu.idle 1000
+ )
+ _colorList cpu
+ )
+
+ _link 0 2 west "West link"
+
+ # Add xing
+ _xing 1 0 3 3 west east east west
+
+ # Add a link and a pipe with eastern orientation
+ _pipe 4 0 east (
+ _pipeTag "East Pipe"
+ _metrics (
+ kernel.all.cpu.user 1000
+ kernel.all.cpu.sys 1000
+ kernel.all.cpu.idle 1000
+ )
+ _colorList cpu
+ )
+ _link 4 2 east "East link"
+ )
+)
+.fi
+.ft R
+.in
+.SH SEE ALSO
+.BR pmview (1).
generated by cgit v1.2.3 (git 2.39.1) at 2025-04-27 22:44:13 +0000