1PMLOGCONF(1) General Commands Manual PMLOGCONF(1)
2
6 pmlogconf - create/edit a pmlogger configuration file
7
9 pmlogconf [-cqrv?] [-d groupsdir] [-h host] configfile
10
12 pmlogconf may be used to create and modify a generic configuration file
13 for the PCP archive logger, pmlogger(1).
14 If configfile does not exist, pmlogconf will create a generic configu‐
16 ration file with a default set of enabled metrics and logging inter‐
17 vals.
18 Once created, configfile may be used with the -c option to pmlogger(1)
20 to select performance metrics and specify logging intervals for a PCP
21 archive.
22 If configfile does exist, pmlogconf will prompt for input from the user
24 to enable or disable groups of related performance metrics and to con‐
25 trol the logging interval for each enabled group.
26 Group selection requires a simple y (yes) or n (no) response to the
28 prompt Log this group?.
29 Other responses at this point may be used to select additional control
31 functions as follows:
32 m Report the names of the metrics in the current group.
34 q Finish with group selection (quit) and make no further
36 changes to this group or any subsequent group.
37 /pattern Make no change to this group but search for a group contain‐
39 ing pattern in the description of the group or the names of
40 the associated metrics.
41 A logging interval is specified by responding to the Logging interval?
43 prompt with the keywords once or default or a valid pmlogger(1) inter‐
44 val specification of the form ``every N timeunits'' or simply ``N time‐
45 units '' (the every is optional) where N is an unsigned integer and
46 timeunits is one of the keywords msec, millisecond, sec, second, min,
47 minute, hour or the plural form of one of the keywords.
48 When run from automated logging setup processes, the -c option is used
50 to indicate that pmlogconf is in auto-create mode and no interactive
51 dialog takes place. The output configfile has an additional comment
52 message and timestamp indicating this fact, so that it can be identi‐
53 fied and subsequently updated using -c again. This option is not
54 appropriate for interactive use of the tool.
55 The -q option suppresses the logging interval dialog and preserves the
57 current interval from configfile.
58 More verbose output may be enabled with the -v option.
60
62 When an initial configfile is created, the default specifications come
63 from a set of group files below the groupsdir specified with the -d
64 option (the default groupsdir is $PCP_VAR_DIR/config/pmlogconf which is
65 most commonly correct, so the -d option is rarely used in practice).
66 The directory structure below groupsdir is arbitrary as all regular
68 files will be found by recursive descent and considered, so add-on
69 products and PMDA developers can easily extend the available defaults
70 to pmlogconf by adding new directories and/or group files below groups‐
71 dir.
72 These group files are processed in the following ways:
74 · When a new configfile is created, all group files are processed.
76 · Whenever pmlogconf is run with an existing configfile, groupsdir is
78 traversed to see if any new groups have been defined and should be
79 considered for inclusion in configfile.
80 · When pmlogconf processes a group in configfile that is enabled, the
82 list of metrics associated with the group is taken from the group
83 file (and replaces any previous list of metrics associated with this
84 group in configfile).
85 · When either the -r (reprobe) or the -c (auto-create) command line
87 option is specified, every group (not just newly discovered ones) is
88 reprocessed to see if it should be considered for inclusion in con‐
89 figfile.
90 · If a group is found in configfile but the corresponding group does
92 not exist below groupsdir (as would be the case when a group is made
93 obsolete by a PCP upgrade) then the handling of the group depends on
94 the mode in which pmlogconf is being run. With -c the corresponding
95 group is culled from configfile, otherwise the corresponding group
96 is unchanged in configfile. In either case a warning is issued.
97 Each group file is structured as follows:
99 · The first line must contain #pmlogconf-setup 2.0
101 · Other lines beginning with # are treated as comments.
103 · Blank lines are ignored.
105 · One or more lines starting with the keyword ident are used to pro‐
107 vide the human-readable description of the group.
108 · Non-blank lines beginning with white space define metrics to be
110 associated with this group, one per line. Each metric specification
111 follows the rules for a pmlogger(1) configuration, namely either the
112 name of a non-leaf node in the PMNS (implying all descendent names
113 in the PMNS), or the name of a leaf node in the PMNS optionally fol‐
114 lowed by one or more instance names enclosed by ``['' and ``]''.
115 · A control line starting with one of the keywords probe or force must
117 be present.
118 · An optional logging interval control line begins with the keyword
120 delta followed by one of the pmlogger(1) interval specification
121 described above.
122 · probe control lines have the format:
124 probe metric [condition [state_rule] ]
125 where metric is the name of a PCP metric (must be a leaf node in the
126 PMNS, no instance specification is allowed, and it must not be a
127 derived metric) and the optional condition is the keyword exists
128 (true if metric exists, i.e. is defined in the PMNS) or the keyword
129 values (true if metric exists in the PMNS and has one or more cur‐
130 rent values) or an expression of the form
131 op val
132 where op is one of the awk(1) operators (==, !=, >, >=, <, <=, ~
133 (regular expression match) or !~ (negated regular expression match))
134 and val is a value (arbitrary sequence of characters, excluding a
135 space) and the condition is true if there is some instance of metric
136 that makes the expression true.
137 If the condition is missing, the default is exists.
139 When an explicit condition is provided, there may also be an
141 optional state_rule of the form
142 ? true_state : false_state
143 where true_state (applies if condition is true) and false_state
144 (applies if condition is false) are both taken from the keywords
145 include (include and enable the group and the associated metrics in
146 configfile), available (include and disable the group in configfile
147 - a user action of y as described above is needed to enable the
148 group and add the associated metrics into configfile) or exclude
149 (the group is not considered for inclusion in configfile).
150 The default state_rule is
152 ? available : exclude
153 · force control lines begin with the keyword force followed by one of
155 the states defined above, so one of the actions include, exclude or
156 available is applied unconditionally to the group.
157 Probing is only done when a new group is being added to configfile or
159 when the -r command line option is specified. The evaluation of the
160 probing conditions is done by contacting pmcd(1) on hostname (defaults
161 to local:).
162
164 The available command line options are:
165 -c Enable non-interactive, auto-create mode.
167 -d groupdir, --groups=groupdir
169 Specify the path to the groupsdir directory.
170 -h host, --host=host
172 Performance metrics source is pmcd(1) on host, rather than on the
173 default localhost.
174 -q, --quiet
176 Quiet mode, suppress logging interval dialog.
177 -r, --reprobe
179 Reconsider every group for inclusion in the configfile.
180 -v, --verbose
182 Enable verbose mode.
183 -?, --help
185 Display usage message and exit.
186
188 The following group file demonstrates all of the supported syntactic
189 elements.
190 #pmlogconf-setup 2.0
192 ident Example group file
193 ident ... more description
194 delta 1 minute
195 probe sample.secret.foo.one values ? include : exclude
196 sample.secret.foo.one
197 sample.secret.foo.bar # non-leaf in the PMNS
198 sample.colour [ red green ]
199
201 The current version of pmlogconf (2.0) supports a slightly different
202 format for configfile compared to earlier versions. If an old version
203 configfile is presented to pmlogconf it will be converted to the new
204 format.
205
207 Environment variables with the prefix PCP_ are used to parameterize the
208 file and directory names used by PCP. On each installation, the file
209 /etc/pcp.conf contains the local values for these variables. The
210 $PCP_CONF variable may be used to specify an alternative configuration
211 file, as described in pcp.conf(5).
212 pmlogconf overrides any $PCP_DERIVED_CONFIG environment variable to an
214 empty string, for performance reasons.
215 pmlogconf honours the $PMCD_WAIT_TIMEOUT environment variable when
217 probing and creating new pmlogger configuration files. It uses a
218 default timeout value of 10 seconds for this, in the absence of an
219 environment setting.
220
222 pmcd(1), pmlogger(1), pcp.conf(5) and pcp.env(5).
223Performance Co-Pilot PCP PMLOGCONF(1)