'\"macro stdmacro
.\"
.\" Copyright (c) 2020 Ken McDonell.  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.
.\"
.\"
.\" NOTE
.\"	This is the text for pmiectl's man page, it is generated from
.\"	the text for pmlogctl's man page (see mk.pmiectl), so
.\"	DO NOT EDIT THIS FILE
.\"
.TH PMIECTL 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmiectl\f1 \- manage and control Performance Co-Pilot inference engines
.SH SYNOPSIS
\f3pmiectl\f1
[\f3\-afmNV?\f1]
[\f3\-C\f1 \f2check_args\f1]
[\f3\-c\f1 \f2class\f1]
[\f3\-i\f1 \f2ident\f1]
[\f3\-p\f1 \f2policy\f1]
\f2command\f1
[\f2host ...\f1]
.SH DESCRIPTION
.B pmiectl
may be used to manage
.I non-primary
instances of
the Performance Co-Pilot (PCP) inference engine
.BR pmie (1).
This would be most relevant in a PCP inference engine ``farm'' where
many
.BR pmie (1)
instances would be evaluating rules against the performance data collected
from
.BR pmcd (1)
on many remote hosts.
.PP
The
.I primary
.BR pmie (1)
instance is closely linked to the local
.BR pmcd (1)
process and as a consequence shares the same control infrastructure,
namely
.BR systemd (1)
or
the PCP
.BR init (1)
\&``rc scripts''.
This is why the
.I primary
.BR pmie (1)
instance
.I cannot
be managed with
.BR pmiectl .
.PP
For brevity in the description below, the term ``instance'' means a
.BR pmie (1)
instance.
.PP
All
instances managed by
.BR pmiectl ,
.BR pmie_check (1)
and
.BR pmie_daily (1)
abide by the following rules:
.IP 1. 3n
Each
instance is fetching performance data from a single
.BR pmcd (1)
(i.e. one host), but each
.BR pmcd (1)
may be providing performance data to zero, one or more
.BR pmie (1)
processes running on one or more hosts.
.IP 2. 3n
On the local host, each
.BR pmie (1)
instance
must be specified once in a
.BR pmie_check (1)
control file and
.BR pmie (1)
creates a unique log file,
named in the 4th parameter of the associated control
file entry
(see the CONFIGURATION section of
.BR pmie_check (1)).
.IP 3. 3n
Each
instance belongs to exactly one
.BR class ,
optionally named using a
.B $class=...
assignment in the associated control file.
The special
.B default
class is reserved for all instances that do not have an
associated
.B $class=...
assignment.
For reporting purposes (refer to the
.B summary
command below), the
.I primary
.BR pmie (1)
instance is automatically assigned to the special
.B primary
class.
.PP
Each
.B pmiectl
execution manages one or more
instances updating the associated control files
and then running
.BR pmie_check (1)
to effect the desired change.
.PP
The
.I host
arguments are usually valid host names.
For all commands
.I except
.B create
and
.B cond-create
(described below)
the
.I host
arguments may also be
.BR egrep (1)
regular expressions that match the
.I whole
of a valid host name, so the pattern used is actually
.BI ^ host $ \c
\&.
For example
.B foo.*
(matches all host names beginning with ``foo'')
or
.B .*foo
(matches all host names ending with ``foo'')
or
.B .*[fF][oO][oO].*
(matches all host names containing ``foo'' in upper, lower or mixed case).
.PP
The combination of a
.I class
from the optional
.B \-c
option (or
.BR default )
and the
.I host
arguments to each
.I command
identifies a
.I target
.I of
.I set
instances to which the
.I command
operation should be applied.
.PP
The
.B \-i
option may be used with the
.B create
or
.B cond-create
commands to override the instance identity that is specified
in the ident section of the class policy file
(see the CLASS POLICY FILE section below).
Since the identifier must be unique across all instances and all
classes, it only makes sense to use this option when there is a single
.I host
argument.
.PP
Given the tasks that
.B pmiectl
is undertaking it usually must be run as ``root'', the exceptions
being the
.B status
command or when the
.B \-N
option is specified.
.SH COMMANDS
.I command
is one of the following:
.TP 4
\f3check\f1
Check the status of all currently configured pmie instances
and restart any that have failed.
If the
.B \-m
flag is given on systemd(1) platforms,
also migrate matching (and new) processes to the \fBpmie_farm\fP service.
.TP 4
\f3create\f1
Create new instances in the class
.I classname
(\c
.B default
by default) for the
.I host
hosts.
The name of the class is used to identify a class policy file
(see the CLASS POLICY FILE section below) which provides a template for
each new control file with
.B %h
replaced by
.I host
and
.B %i
replaced by the instance's (unique) identifier from the ident section of the
class policy file or
.I ident
from the
.B \-i
option.
.RS 4n
.PP
The
.B \-p
option may be used to identify a class policy file other than
the one found in the standard place, i.e. \c
.I $PCP_SYSCONF_DIR/pmie/class.d/\c
.IR classname .
.PP
At least one
.I host
must be specified for the
.B create
command.
.RE
.TP 4
\f3cond-create\f1
Similar to
.B create
but the instance will only be created if one of the conditions in the
create section of associated class policy file(s) evaluates to true.
.RS 4n
.PP
If a
.B \-c
option is specified, then only the class
.I classname
will be considered, otherwise
.B all
classes will be considered.
In the latter case, if none of the conditions in any of the classes evaluates
to true, the the special
.B pmfind
class is used (this is the ``default'' class for the
.B cond-create
command when all else fails).
.PP
If more than one class evaluates to true then a composite
.BR pmie (1)
configuration
file is created and the instance is also assigned to the special
.B pmfind
class.
The composite configuration file may contain a mix of explicit configuration
clauses and the more general conditional configuration clauses as understood
by the
.BR pmieconf (1)
tool.
.RE
.TP 4
\f3start\f1
Start the target set of instances.
.RS 4n
.PP
If the target set intentionally contains more than one instance, then the
.BR \-a
option should be used (this is designed to reduce the
risk of accidentally starting a
potentially large number of
.BR pmie (1)
processes).
.PP
If an
instance in the target set is already started, no change is made
(see the
.B restart
command to force new instances
to be launched).
.RE
.TP 4
\f3stop\f1
Stop the target set of instances.
.RS 4n
.PP
If the target set intentionally contains more than one
instance, then the
.BR \-a
option should be used (this is designed to reduce the
risk of accidentally stopping a
potentially large number of
.BR pmie (1)
processes).
.PP
If an
instance in the target set is already stopped, no change is made
but a warning is issued.
.RE
.TP 4
\f3restart\f1
Stop and then start the target set of instances.
.RS 4n
.PP
If the target set intentionally contains more than one instance, then the
.BR \-a
option should be used (this is designed to reduce the
risk of accidentally stopping and starting a
potentially large number of
.BR pmie (1)
processes).
.PP
If an
instance in the target set is already stopped,
a warning is issued before the instance is started.
.RE
.TP 4
\f3status\f1
Report the status of the target set of instances.
If there is no
.B \-c
option specified and no
.I host
arguments, i.e. the target set is empty, then
.I all
instances will be reported.
.TP 4
\f3destroy\f1
Destroy the target set of instances.
At the end of this operation the associated
.BR pmie (1)
processes will have been stopped and the relevant
control file information removed.
.RS 4n
.PP
If the target set intentionally contains more than one instance, then the
.BR \-a
option should be used (this is designed to reduce the
risk of accidentally terminating a
potentially large number of
.BR pmie (1)
processes and removing their
.BR pmie_check (1)
configurations).
.PP
The policy file linked to the class of an
instance to be destroyed may contain a
.B destroy
section that may influence if and how the destroy operation
should be performed.
This may require a
.B \-p
option to find the associated class policy file.
.PP
The class policy checking can be by-passed using the
.B \-f
(force) command line option.
.RE
.SH CLASS POLICY FILE
A class policy file contains a number of sections, each section
begins with a line that simply starts with
the name of the section followed enclosed by ``['' and ``]''.
.PP
Lines beginning with a hash (#) are treated as comments and ignored.
Blank or empty lines are also ignored.
.PP
The typical location of the policy file for the class
.I foo
is
.I $PCP_SYSCONF_DIR/pmie/class.d/\c
.IR foo .
.TP 4n
.B [class]
The optional class name section names the class.
If it is missing, the name of the policy file (stripped of any directory
prefix) is used as the name of the class.
.TP 4n
.B [ident]
The ident section specifies the template to be used for
the instance identifier to be given to each member
of the class.
This identifier needs to be unique across all instances and all
classes, and it needs
to be a valid file name in the local filesystem, so would normally
contain the class name and the macro
.BR %h ,
e.g. \c
.BR foo-%h .
The macro is replaced by the
.I host
when each instance is created.
.TP 4n
.B [control]
The control section consists of one or more lines of template text
that will be used to create the control file for each instance.
This must at least include the
.BR pmie_check (1)
control line to specify how to start the associated
.BR pmie (1)
process; this line contains fields separated by white space as follows:
.PD 0
.RS 4n
.IP 1. 4n
the hostname, usually the macro
.B %h
.IP 2. 4n
.B n
to indicate this is a non-primary instance
.IP 3. 4n
the ``socks'' flag, typically
.B n
.IP 4. 4n
the pathname used by
.BR pmie (1)
for the log file; this needs to be unique and is usually
specified using the
.BR pmie_check (1)
macro
.B PCP_LOG_DIR
as the start of the path, followed by
.BR pmie ,
and then the instance's unique directory
.BR %i ,
e.g. \c
.B PCP_LOG_DIR/pmie/%i/pmie.log
.IP 5. 4n
additional parameters to
.BR pmie (1)
which probably include at least a
.B \-c
option to provide a configuration file that describes which
rules should be evaluated
for instances of this class, which may be the same for all
instances in this class, or it may include the
.B %i
macro to use a different configuration file for each instance.
Note that if this configuration file does not exist, it will be
created using
.BR pmieconf (1)
the first time
.BR pmie_check (1)
is run.
.PD
.PP
.I Before
the control line there should be a line that defines the version of
the control line that follows, i.e.
.br
.B $version=1.1
.br
If this is missing,
.B pmiectl
will assume the version is 1.1 and insert the line when the instance is created.
.PP
.B pmiectl
will also add the class name during creation. e.g.
.br
.B $class=foo
.RE
.TP 4n
.B [create]
The create section defines the conditions that must be met before an
instance will be created with the
.B cond-create
command.
The intent is to allow different decisions to be made when a new host
running
.BR pmcd (1)
is discovered, e.g. by
.BR pmfind (1).
.RS 4n
.PP
Each non-blank line in the create section is a condition
of the form \fIfunction\fR(\fIarg\fR), where
.I function
is one of the following:
.TP 4n
.I exists
.I arg
is the name of a performance metric and
.I exits
evaluates to true if that metric exists in the Performance Metrics
Name Space (PMNS) on the remote host
.TP 4n
.I values
.I arg
is the name of a performance metric in the remote PMNS and
.I values
evaluates to true if some instance of that metric has a value
on the remote host
.TP 4n
.I condition
.I arg
is a derived metric expression in the format supported by
.BR pmRegisterDerived (3),
and
.I condition
evaluates to true if the value of that expression on the remote
host is greater than zero
.TP 4n
.I hostname
.I arg
is a regular expression in the style of
.BR egrep (1)
and
.I hostname
evaluates to true if the remote host name matches
.I arg
.RE
.TP 4n
.B [destroy]
The destroy section defines the policy to be applied when an
instance is destroyed.
.RS 4n
.PP
The intent is to allow different decisions to be made when discovery
service, e.g.
.BR pmfind (1),
notices that a host associated with an instance is no longer
present.
But in the current version this is not implemented and the destroy
section syntax and semantics is not yet defined.
.RE
.PP
A sample class policy file is as follows:
.RS 4n
.PP
.ft CR
.nf
# policy file for the foo class
[class]
foo
[ident]
foo-%h

[control]
$version=1.1
%h n n PCP_LOG_DIR/pmie/%i/pmie.log -c foo-metrics.config

[create]
# matches all hosts
hostname(.*)

[destroy]
# still to be defined
.fi
.ft
.RE
.SH OPTIONS
The available command line options are:
.TP 5
\fB\-a\fR, \fB\-\-all\fR
Apply action to all matching instances.
By default only one instance definition is expected and acted upon.
.TP
\fB\-c\fR \fIclass\fR, \fB\-\-class\fR=\fIclass\fR
Set the name of the class for which
.BR pmie (1)
instances belong to as
.IR class .
.TP
\fB\-C\fR \fIcheck_args\fR, \fB\-\-checkargs\fR=\fIcheck_args\fR
.I check_args
are additional command line arguments for
.BR pmie_check (1)
when it is called.
This is most useful for options like
.BR \-V .
Multiple
.B \-C
options may be used and the various
.I check_args
options will be accumulated and all passed to
.BR pmie_check (1).
.TP
\fB\-f\fR, \fB\-\-force\fR
Force action if possible.
.TP
\fB\-i\fR \fIident\fR, \fB\-\-ident\fR=\fIident\fR
Override instance identifier with
.IR ident .
This option applies only for the commands
.B create
and
.BR cond\-create .
.TP
\fB\-N\fR, \fB\-\-showme\fR
Runs
.B pmiectl
in a ``show me'' or ``dry run'' mode where the intent of the
command is shown, but no changes are made.
.TP
\fB\-m\fP, \fB\-\-migrate\fP
When used with the \fBcreate\fP or \fBcheck\fP commands on
.BR systemd (1)
platforms, also migrate new or existing non-primary \fBpmie\fP processes
to the \fBpmie_farm\fP service.
This is normally done automatically by the \fBpmie_farm_check\fP service,
which is timer driven (so there may be a few minutes delay before
automatic migration is initiated).
.TP
\fB\-p\fR \fIpolicy\fR, \fB\-\-policy\fR=\fIpolicy\fR
Use
.I policy
as the class policy file.
Defaults to
.IR $PCP_SYSCONF_DIR/pmie/class.d/<class> .
.TP
\fB\-V\fR, \fB\-\-verbose\fR
Enable verbose mode.
Using this option twice increases verbosity.
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.SH SEE ALSO
.BR egrep (1),
.BR init (1),
.BR PCPIntro (1),
.BR pmcd (1),
.BR pmieconf (1),
.BR pmie (1),
.BR pmie_check (1),
.BR pmie_daily (1),
.BR systemd (1),
.BR PMAPI (3),
.BR pmDerivedRegister (3)
and
.BR pcp.conf (5).