1PMLOGCONF(1) General Commands Manual PMLOGCONF(1)
2
6 pmlogconf - create/edit a pmlogger configuration file
7
9 pmlogconf [-cqrvV?] [-d groupsdir] [-g grouptag] [-h host] [-s group‐
10 file] configfile
11
13 pmlogconf may be used to create and modify a generic configuration file
14 for the PCP archiver, pmlogger(1).
15 If configfile does not exist, pmlogconf will create a generic configu‐
17 ration file with a default set of enabled metrics and logging inter‐
18 vals.
19 Once created, configfile may be used with the -c option to pmlogger(1)
21 to select performance metrics and specify logging intervals for a PCP
22 archive.
23 If configfile does exist, pmlogconf will prompt for input from the user
25 to enable or disable groups of related performance metrics and to con‐
26 trol the logging interval for each enabled group.
27 Group selection requires a simple y (yes) or n (no) response to the
29 prompt Log this group?.
30 Other responses at this point may be used to select additional control
32 functions as follows:
33 m Report the names of the metrics in the current group.
35 q Finish with group selection (quit) and make no further
37 changes to this group or any subsequent group.
38 /pattern Make no change to this group but search for a group contain‐
40 ing pattern in the description of the group or the names of
41 the associated metrics.
42 A logging interval is specified by responding to the Logging interval?
44 prompt with the keywords once or default or a valid pmlogger(1) inter‐
45 val specification of the form ``every N timeunits'' or simply ``N time‐
46 units '' (the every is optional) where N is an unsigned integer and
47 timeunits is one of the keywords msec, millisecond, sec, second, min,
48 minute, hour or the plural form of one of the keywords.
49 When run from automated logging setup processes, the -c option is used
51 to indicate that pmlogconf is in auto-create mode and no interactive
52 dialog takes place. The output configfile has an additional comment
53 message and timestamp indicating this fact, so that it can be identi‐
54 fied and subsequently updated using -c again. This option is not ap‐
55 propriate for interactive use of the tool.
56 The -q option suppresses the logging interval dialog and preserves the
58 current interval from configfile.
59 More verbose output may be enabled with the -v option.
61
63 When an initial configfile is created, the default specifications come
64 from a set of group files below the groupsdir specified with the -d op‐
65 tion (the default groupsdir is $PCP_VAR_DIR/config/pmlogconf which is
66 most commonly correct, so the -d option is rarely used in practice).
67 The directory structure below groupsdir is arbitrary as all regular
69 files will be found by recursive descent and considered, so add-on
70 products and PMDA developers can easily extend the available defaults
71 to pmlogconf by adding new directories and/or group files below groups‐
72 dir.
73 These group files are processed in the following ways:
75 • When a new configfile is created, all group files are processed.
77 • Whenever pmlogconf is run with an existing configfile, groupsdir is
79 traversed to see if any new groups have been defined and should be
80 considered for inclusion in configfile.
81 • When pmlogconf processes a group in configfile that is enabled, the
83 list of metrics associated with the group is taken from the group
84 file (and replaces any previous list of metrics associated with this
85 group in configfile).
86 • When either the -r (reprobe) or the -c (auto-create) command line
88 option is specified, every group (not just newly discovered ones) is
89 reprocessed to see if it should be considered for inclusion in con‐
90 figfile.
91 • If a group is found in configfile but the corresponding group does
93 not exist below groupsdir (as would be the case when a group is made
94 obsolete by a PCP upgrade) then the handling of the group depends on
95 the mode in which pmlogconf is being run. With -c the corresponding
96 group is culled from configfile, otherwise the corresponding group
97 is unchanged in configfile. In either case a warning is issued.
98 Each group file is structured as follows:
100 • The first line must contain #pmlogconf-setup 2.0
102 • Other lines beginning with # are treated as comments.
104 • Blank lines are ignored.
106 • One or more lines starting with the keyword ident are used to pro‐
108 vide the human-readable description of the group.
109 • Non-blank lines beginning with white space define metrics to be as‐
111 sociated with this group, one per line. Each metric specification
112 follows the rules for a pmlogger(1) configuration, namely either the
113 name of a non-leaf node in the PMNS (implying all descendent names
114 in the PMNS), or the name of a leaf node in the PMNS optionally fol‐
115 lowed by one or more instance names enclosed by ``['' and ``]''.
116 • A control line starting with one of the keywords probe or force must
118 be present.
119 • An optional logging interval control line begins with the keyword
121 delta followed by one of the pmlogger(1) interval specification de‐
122 scribed above.
123 • probe control lines have the format:
125 probe metric [condition [state_rule] ]
126 where metric is the name of a PCP metric (must be a leaf node in the
127 PMNS, no instance specification is allowed, and it must not be a de‐
128 rived metric) and the optional condition is the keyword exists (true
129 if metric exists, i.e. is defined in the PMNS) or the keyword values
130 (true if metric exists in the PMNS and has one or more current val‐
131 ues) or an expression of the form
132 op val
133 where op is one of the awk(1) operators (==, !=, >, >=, <, <=, ~
134 (regular expression match) or !~ (negated regular expression match))
135 and val is a value (arbitrary sequence of characters, excluding a
136 space) and the condition is true if there is some instance of metric
137 that makes the expression true.
138 If the condition is missing, the default is exists.
140 When an explicit condition is provided, there may also be an op‐
142 tional state_rule of the form
143 ? true_state : false_state
144 where true_state (applies if condition is true) and false_state (ap‐
145 plies if condition is false) are both taken from the keywords in‐
146 clude (include and enable the group and the associated metrics in
147 configfile), available (include and disable the group in configfile
148 - a user action of y as described above is needed to enable the
149 group and add the associated metrics into configfile) or exclude
150 (the group is not considered for inclusion in configfile).
151 The default state_rule is
153 ? available : exclude
154 • force control lines begin with the keyword force followed by one of
156 the states defined above, so one of the actions include, exclude or
157 available is applied unconditionally to the group.
158 Probing is only done when a new group is being added to configfile or
160 when the -r command line option is specified. The evaluation of the
161 probing conditions is done by contacting pmcd(1) on hostname (defaults
162 to local:).
163
165 The available command line options are:
166 -c Enable non-interactive, auto-create mode.
168 -d groupdir, --groups=groupdir
170 Specify the path to the groupsdir directory.
171 -g grouptag, --group=grouptag
173 Query logging state for the specific logging group named grouptag.
174 -h host, --host=host
176 Performance metrics source is pmcd(1) on host, rather than on the
177 default localhost.
178 -q, --quiet
180 Quiet mode, suppress logging interval dialog.
181 -r, --reprobe
183 Reconsider every group for inclusion in the configfile.
184 -s groupfile, --setup=groupfile
186 Report the default logging state for the one logging group in
187 groupfile. This is equivalent output to that produced by the re‐
188 tired pmlogconf-setup shell script from earlier versions of PCP.
189 -v, --verbose
191 Enable verbose mode.
192 -V, --version
194 Display version number and exit.
195 -?, --help
197 Display usage message and exit.
198
200 The following group file demonstrates all of the supported syntactic
201 elements.
202 #pmlogconf-setup 2.0
204 ident Example group file
205 ident ... more description
206 delta 1 minute
207 probe sample.secret.foo.one values ? include : exclude
208 sample.secret.foo.one
209 sample.secret.foo.bar # non-leaf in the PMNS
210 sample.colour [ red green ]
211
213 The current version of pmlogconf (2.0) supports a slightly different
214 format for configfile compared to earlier versions. If an old version
215 configfile is presented to pmlogconf it will be converted to the new
216 format.
217
219 Environment variables with the prefix PCP_ are used to parameterize the
220 file and directory names used by PCP. On each installation, the file
221 /etc/pcp.conf contains the local values for these variables. The
222 $PCP_CONF variable may be used to specify an alternative configuration
223 file, as described in pcp.conf(5).
224 pmlogconf overrides any $PCP_DERIVED_CONFIG environment variable to an
226 empty string, for performance reasons.
227 pmlogconf honours the $PMCD_WAIT_TIMEOUT environment variable when
229 probing and creating new pmlogger configuration files. It uses a de‐
230 fault timeout value of 10 seconds for this, in the absence of an envi‐
231 ronment setting.
232
234 pmcd(1), pmlogger(1), pcp.conf(5) and pcp.env(5).
235Performance Co-Pilot PCP PMLOGCONF(1)