1PMLOGGER.CONTROL(5) File Formats Manual PMLOGGER.CONTROL(5)
2
6 pmlogger.control - control files for Performance Co-Pilot archiving
7
9 Historical archiving of performance data for Performance Co-Pilot (see
10 PCPIntro(1)) uses pmlogger(1) and one or more instances of pmlogger may
11 be managed by pmlogger_check(1) and pmlogger_daily(1).
12 pmlogger_check(1) may be run at any time of the day and is intended to
14 check that the desired set of pmlogger processes are running. If not,
15 it (re-)starts any missing logger processes. By default, pmlog‐
16 ger_check(1) also calls pmlogger_daily(1) with a -K option to execute
17 any required archive compression tasks.
18 pmlogger_daily(1) is intended to be run once per day, preferably in the
20 early morning, as soon after midnight as practicable. Its task is to
21 aggregate, rotate and perform general housekeeping for one or more sets
22 of PCP archives.
23 Both pmlogger_check(1) and pmlogger_daily(1) operate on a family of
25 shared control files, namely the $PCP_PMLOGGERCONTROL_PATH file and
26 files within the $PCP_PMLOGGERCONTROL_PATH.d directory. These files
27 must not be writable by any user other than root.
28 The control file(s) should be customized according to the following
30 rules that define for the current version (1.1) of the control file
31 format.
32 1. Lines beginning with a ``#'' are comments. A special case is lines
34 beginning ``#!#''; these are control lines for a pmlogger that has
35 been stopped using pmlogctl(1).
36 2. Lines beginning with a ``$'' are assumed to be assignments to envi‐
37 ronment variables in the style of sh(1), and all text following the
38 ``$'' will be eval'ed by the script reading the control file, and
39 the corresponding variable exported into the environment. This is
40 particularly useful to set and export variables into the environ‐
41 ment of the administrative scripts, e.g.
42 $ PMCD_CONNECT_TIMEOUT=20
43 If the value to the right of the ``='' contains any white space,
44 then the value should be enclosed in double (") or single (')
45 quotes.
46 3. There must be a version line in the control file of the form:
47 $version=1.1
48 4. Fields within a line of the control file(s) are usually separated
49 by one or more spaces or tabs (although refer to the description of
50 the directory field below for some important exceptions).
51 5. There should be one line in the control file(s) for each pmlogger
52 instance with at least 4 fields of the form:
53 host primary socks directory args ...
54 6. The host field is the name of the host that is the source of the
55 performance metrics for this pmlogger instance. The reserved word
56 LOCALHOSTNAME will be replaced by the name of the local host.
57 7. The primary field indicates if this is a primary pmlogger instance
58 (y) or not (n). Since the primary logger must run on the local
59 host, and there may be at most one primary logger for a particular
60 host, this field can be y for at most one pmlogger instance, in
61 which case the host name must be the name of the local host (or LO‐
62 CALHOSTNAME).
63 8. The socks field indicates if this pmlogger instance needs to be
64 started under the control of pmsocks(1) to connect to a pmcd(1)
65 through a firewall (y or n).
66 9. The directory field is a directory name. All archive files associ‐
67 ated with this pmlogger instance will be created in this directory,
68 and this will be the current directory for the execution of any
69 programs required to maintain those archives. A useful convention
70 is that primary logger archives for the local host with hostname
71 myhost are maintained in the directory $PCP_ARCHIVE_DIR/myhost
72 (this is where the default pmlogger start-up script in
73 $PCP_RC_DIR/pcp will create the archives), while archives for the
74 remote host mumble are maintained in $PCP_ARCHIVE_DIR/mumble.
75 10. The directory field may contain embedded shell syntax that will be
76 evaluated by sh(1) to produce the real directory name to be used.
77 The allowed constructs are:
78 • Any text (including white space) enclosed with $( and ) will be
79 interpreted as a shell command.
80 • Any text (including white space) enclosed with ` and ` (back
81 quotes) will be interpreted as a shell command.
82 • Within a single line only one style of embedded shell command is
83 allowed, so either $(...) or `...`, but not both.
84 • An initial double quote (") followed by arbitrary text (including
85 white space, but excluding an embedded double quote) and a final
86 double quote.
87 • An initial single quote (') followed by arbitrary text (including
88 white space, but excluding an embedded single quote) and a final
89 single quote.
90 • Any word containing a $ (assumed to introduce an environment
91 variable name).
92 11. In the directory field, the reserved word LOCALHOSTNAME will be re‐
93 placed by the name of the local host.
94 12. The optional args field and any remaining fields are interpreted as
95 arguments to be passed to pmlogger(1). Most typically this would
96 be at least the -c option to specify the metrics to be logged and
97 the logging frequencies.
98 The following sample control lines specify a primary logger on the lo‐
100 cal host (bozo), and non-primary loggers to collect and log performance
101 metrics from the hosts wobbly, boing and the local host (i.e. bozo).
102 $version=1.1
104 bozo y n $PCP_ARCHIVE_DIR/bozo -c config.default
105 wobbly n n "/store/wobbly/$(date +%Y)" -c ./wobbly.config
106 boing n n $PCP_ARCHIVE_DIR/boing -c ./pmlogger.config
107 LOCALHOSTNAME n n /cluster/LOCALHOSTNAME -c ./precious.config
108
110 The periodic execution of pmlogger_check(1) and pmlogger_daily(1) is
111 controlled by either systemd(1) or cron(8).
112 Typical crontab(5) entries are provided in $PCP_SYSCONF_DIR/pmlog‐
114 ger/crontab (unless installed by default in /etc/cron.d already) and
115 shown below.
116 # daily processing of archives
118 14 0 * * * $PCP_BINADM_DIR/pmlogger_daily
119 # every 30 minutes, check pmlogger instances are running
120 25,55 * * * * $PCP_BINADM_DIR/pmlogger_check
121 When using systemd(1) on Linux, no crontab entries are needed as the
123 timer mechanism provided by systemd is used instead to achieve the same
124 period execution as the crontab example above.
125
127 $PCP_PMLOGGERCONTROL_PATH
128 the PCP logger control file. For a new installation this file
129 contains no pmlogger(1) control lines (the real control files are
130 all in the $PCP_PMLOGGERCONTROL_PATH.d directory), but this file
131 is still processed to support any legacy configurations therein
132 from earlier PCP releases.
133 Warning: this file must not be writable by any user other than
134 root.
135 $PCP_PMLOGGERCONTROL_PATH.d
137 optional directory containing additional PCP logger control files,
138 with one or more per pmlogger specification per file.
139 Warning: the files herein must not be writable by any user other
140 than root.
141 $PCP_SYSCONF_DIR/pmlogger/crontab
143 sample crontab for automated script execution by $PCP_USER (or
144 root). Exists only if the platform does not support the
145 /etc/cron.d mechanism.
146
148 Environment variables with the prefix PCP_ are used to parameterize the
149 file and directory names used by PCP. On each installation, the file
150 /etc/pcp.conf contains the local values for these variables. The
151 $PCP_CONF variable may be used to specify an alternative configuration
152 file, as described in pcp.conf(5).
153
155 PCPIntro(1), pmcd(1), pmlogctl(1), pmlogger(1), pmlogger_check(1), pm‐
156 logger_daily(1), pmlogger_daily_report(1), pmsocks(1), systemd(1) and
157 cron(8).
158Performance Co-Pilot PCP PMLOGGER.CONTROL(5)