1PMLOGCONF(1) General Commands Manual PMLOGCONF(1)
2
6 pmlogconf - create/edit a pmlogger configuration file
7
9 $PCP_BINADM_DIR/pmlogconf [-cqrv] [-d groupsdir] [-h hostname] config‐
10 file
11
13 pmlogconf may be used to create and modify a generic configuration file
14 for the PCP archive logger, 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 add a message and timestamp indicating this fact. This option is
52 not appropriate for interactive use of the tool.
53 The -q option suppresses the logging interval dialog and preserves the
55 current interval from configfile.
56 More verbose output may be enabled with the -v option.
58
60 When an initial configfile is created, the default specifications come
61 from a set of group files below the groupsdir specified with the -d
62 option (the default groupsdir is $PCP_VAR_DIR/config/pmlogconf which is
63 most commonly correct, so the -d option is rarely used in practice).
64 The directory structure below groupsdir is arbitrary as all regular
66 files will be found by recursive descent and considered, so add-on
67 products and PMDA developers can easily extend the available defaults
68 to pmlogconf by adding new directories and/or group files below groups‐
69 dir.
70 These group files are processed in the following ways:
72 · When a new configfile is created, all group files are processed.
74 · Whenever pmlogconf is run with an existing configfile, groupsdir is
76 traversed to see if any new groups have been defined and should be
77 considered for inclusion in configfile.
78 · When pmlogconf processes a group in configfile that is enabled, the
80 list of metrics associated with the group is taken from the group
81 file (and replaces any previous list of metrics associated with this
82 group in configfile).
83 · When the -r (reprobe) command line option is specified, every group
85 (not just newly discovered ones) is reprocessed to see if it should
86 be considered for inclusion in configfile.
87 Each group file is structured as follows:
89 · The first line must contain #pmlogconf-setup 2.0
91 · Other lines beginning with # are treated as comments.
93 · Blank lines are ignored.
95 · One or more lines starting with the keyword ident are used to pro‐
97 vide the human-readable description of the group.
98 · Non-blank lines beginning with white space define metrics to be
100 associated with this group, one per line. Each metric specification
101 follows the rules for a pmlogger(1) configuration, namely either the
102 name of a non-leaf node in the PMNS (implying all descendent names
103 in the PMNS), or the name of a leaf node in the PMNS optionally fol‐
104 lowed by one or more instance names enclosed by ``['' and ``]''.
105 · A control line starting with one of the keywords probe or force must
107 be present.
108 · An optional logging interval control line begins with the keyword
110 delta followed by one of the pmlogger(1) interval specification
111 described above.
112 · probe control lines have the format:
114 probe metric [condition [state_rule] ]
115 where metric is the name of a PCP metric (must be a leaf node in the
116 PMNS and no instance specification is allowed) and the optional con‐
117 dition is the keyword exists (true if metric exists, i.e. is defined
118 in the PMNS) or the keyword values (true if metric exists in the
119 PMNS and has one or more current values) or an expression of the
120 form
121 op val
122 where op is one of the awk(1) operators (==, !=, >, >=, <, <=, ~
123 (regular expression match) or !~ (negated regular expression match))
124 and val is a value (arbitrary sequence of characters, excluding a
125 space) and the condition is true if there is some instance of metric
126 that makes the expression true.
127 If the condition is missing, the default is exists.
129 When an explicit condition is provided, there may also be an
131 optional state_rule of the form
132 ? true_state : false_state
133 where true_state (applies if condition is true) and false_state
134 (applies if condition is false) are both taken from the keywords
135 include (include and enable the group and the associated metrics in
136 configfile), available (include and disable the group in configfile
137 - a user action of y as described above is needed to enable the
138 group and add the associated metrics into configfile) or exclude
139 (the group is not considered for inclusion in configfile).
140 The default state_rule is
142 ? available : exclude
143 · force control lines begin with the keyword force followed by one of
145 the states defined above, so one of the actions include, exclude or
146 available is applied unconditionally to the group.
147 Probing is only done when a new group is being added to configfile or
149 when the -r command line option is specified. The evaluation of the
150 probing conditions is done by contacting pmcd(1) on hostname (defaults
151 to local:).
152
154 The following group file demonstrates all of the supported syntactic
155 elements.
156 #pmlogconf-setup 2.0
158 ident Example group file
159 ident ... more description
160 delta 1 minute
161 probe sample.secret.foo.one values ? include : exclude
162 sample.secret.foo.one
163 sample.secret.foo.bar # non-leaf in the PMNS
164 sample.colour [ red green ]
165
167 The current version of pmlogconf (2.0) supports a slightly different
168 format for configfile compared to earlier versions. If an old version
169 configfile is presented to pmlogconf it will be converted to the new
170 format.
171
173 Environment variables with the prefix PCP_ are used to parameterize the
174 file and directory names used by PCP. On each installation, the file
175 /etc/pcp.conf contains the local values for these variables. The
176 $PCP_CONF variable may be used to specify an alternative configuration
177 file, as described in pcp.conf(5).
178
180 pmcd(1), pmlogger(1), pcp.conf(5) and pcp.env(5).
181Performance Co-Pilot PCP PMLOGCONF(1)