pmlogconf(1)
NAME
pmlogconf - create/edit a pmlogger configuration file
SYNOPSIS
pmlogconf [-cqrv] [-d groupsdir] [-h hostname] configfile
DESCRIPTION
pmlogconf may be used to create and modify a generic configuration file for the PCP archive logger, pmlogger(1). If configfile does not exist, pmlogconf will create a generic configuration file with a default set of enabled metrics and logging intervals. Once created, configfile may be used with the -c option to pmlogger(1) to select performance metrics and specify logging intervals for a PCP archive. If configfile does exist, pmlogconf will prompt for input from the user to enable or disable groups of related performance metrics and to control the logging interval for each enabled group. Group selection requires a simple y (yes) or n (no) response to the prompt Log this group?. Other responses at this point may be used to select additional control functions as follows: m Report the names of the metrics in the current group. q Finish with group selection (quit) and make no further changes to this group or any subsequent group. /pattern Make no change to this group but search for a group containing pattern in the description of the group or the names of the associated metrics. A logging interval is specified by responding to the Logging interval? prompt with the keywords once or default or a valid pmlogger(1) interval specification of the form ``every N timeunits'' or simply ``N timeunits '' (the every is optional) where N is an unsigned integer and timeunits is one of the keywords msec, millisecond, sec, second, min, minute, hour or the plural form of one of the keywords. When run from automated logging setup processes, the -c option is used to add a message and timestamp indicating this fact. This option is not appropriate for interactive use of the tool. The -q option suppresses the logging interval dialog and preserves the current interval from configfile. More verbose output may be enabled with the -v option.
SETUP GROUP FILES
When an initial configfile is created, the default specifications come
from a set of group files below the groupsdir specified with the -d
option (the default groupsdir is $PCP_VAR_DIR/config/pmlogconf which is
most commonly correct, so the -d option is rarely used in practice).
The directory structure below groupsdir is arbitrary as all regular
files will be found by recursive descent and considered, so add-on
products and PMDA developers can easily extend the available defaults
to pmlogconf by adding new directories and/or group files below
groupsdir.
These group files are processed in the following ways:
* When a new configfile is created, all group files are processed.
* Whenever pmlogconf is run with an existing configfile, groupsdir is
traversed to see if any new groups have been defined and should be
considered for inclusion in configfile.
* When pmlogconf processes a group in configfile that is enabled, the
list of metrics associated with the group is taken from the group
file (and replaces any previous list of metrics associated with this
group in configfile).
* When the -r (reprobe) command line option is specified, every group
(not just newly discovered ones) is reprocessed to see if it should
be considered for inclusion in configfile.
Each group file is structured as follows:
* The first line must contain #pmlogconf-setup 2.0
* Other lines beginning with # are treated as comments.
* Blank lines are ignored.
* One or more lines starting with the keyword ident are used to
provide the human-readable description of the group.
* Non-blank lines beginning with white space define metrics to be
associated with this group, one per line. Each metric specification
follows the rules for a pmlogger(1) configuration, namely either the
name of a non-leaf node in the PMNS (implying all descendent names
in the PMNS), or the name of a leaf node in the PMNS optionally
followed by one or more instance names enclosed by ``['' and ``]''.
* A control line starting with one of the keywords probe or force must
be present.
* An optional logging interval control line begins with the keyword
delta followed by one of the pmlogger(1) interval specification
described above.
* probe control lines have the format:
probe metric [condition [state_rule] ]
where metric is the name of a PCP metric (must be a leaf node in the
PMNS, no instance specification is allowed, and it must not be a
derived metric) and the optional condition is the keyword exists
(true if metric exists, i.e. is defined in the PMNS) or the keyword
values (true if metric exists in the PMNS and has one or more
current values) or an expression of the form
op val
where op is one of the awk(1) operators (==, !=, >, >=, <, <=, ~
(regular expression match) or !~ (negated regular expression match))
and val is a value (arbitrary sequence of characters, excluding a
space) and the condition is true if there is some instance of metric
that makes the expression true.
If the condition is missing, the default is exists.
When an explicit condition is provided, there may also be an
optional state_rule of the form
? true_state : false_state
where true_state (applies if condition is true) and false_state
(applies if condition is false) are both taken from the keywords
include (include and enable the group and the associated metrics in
configfile), available (include and disable the group in configfile
- a user action of y as described above is needed to enable the
group and add the associated metrics into configfile) or exclude
(the group is not considered for inclusion in configfile).
The default state_rule is
? available : exclude
* force control lines begin with the keyword force followed by one of
the states defined above, so one of the actions include, exclude or
available is applied unconditionally to the group.
Probing is only done when a new group is being added to configfile or
when the -r command line option is specified. The evaluation of the
probing conditions is done by contacting pmcd(1) on hostname (defaults
to local:).
EXAMPLE
The following group file demonstrates all of the supported syntactic
elements.
#pmlogconf-setup 2.0
ident Example group file
ident ... more description
delta 1 minute
probe sample.secret.foo.one values ? include : exclude
sample.secret.foo.one
sample.secret.foo.bar # non-leaf in the PMNS
sample.colour [ red green ]
MIGRATION
The current version of pmlogconf (2.0) supports a slightly different format for configfile compared to earlier versions. If an old version configfile is presented to pmlogconf it will be converted to the new format.
PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the file /etc/pcp.conf contains the local values for these variables. The $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5). Note that pmlogconf specifically overrides its own $PCP_DERIVED_CONFIG environment variable to an empty string, for performance reasons.
SEE ALSO
pmcd(1), pmlogger(1), 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.
