1PMLOGCONF(1)                General Commands Manual               PMLOGCONF(1)
2
3
4

NAME

6       pmlogconf - create/edit a pmlogger configuration file
7

SYNOPSIS

9       pmlogconf  [-cqrv?]   [-d groupsdir] [-g grouptag] [-h host] [-s group‐
10       file] configfile
11

DESCRIPTION

13       pmlogconf may be used to create and modify a generic configuration file
14       for the PCP archive logger, pmlogger(1).
15
16       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
20       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
24       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
28       Group  selection  requires  a  simple y (yes) or n (no) response to the
29       prompt Log this group?.
30
31       Other responses at this point may be used to select additional  control
32       functions as follows:
33
34       m         Report the names of the metrics in the current group.
35
36       q         Finish  with  group  selection  (quit)  and  make  no further
37                 changes to this group or any subsequent group.
38
39       /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
43       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
50       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
55       appropriate for interactive use of the tool.
56
57       The -q option suppresses the logging interval dialog and preserves  the
58       current interval from configfile.
59
60       More verbose output may be enabled with the -v option.
61

SETUP GROUP FILES

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
65       option (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
68       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
74       These group files are processed in the following ways:
75
76       ·  When a new configfile is created, all group files are processed.
77
78       ·  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
82       ·  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
87       ·  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
92       ·  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
99       Each group file is structured as follows:
100
101       ·  The first line must contain #pmlogconf-setup 2.0
102
103       ·  Other lines beginning with # are treated as comments.
104
105       ·  Blank lines are ignored.
106
107       ·  One  or  more lines starting with the keyword ident are used to pro‐
108          vide the human-readable description of the group.
109
110       ·  Non-blank lines beginning with white  space  define  metrics  to  be
111          associated 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
117       ·  A control line starting with one of the keywords probe or force must
118          be present.
119
120       ·  An optional logging interval control line begins  with  the  keyword
121          delta  followed  by  one  of  the pmlogger(1) interval specification
122          described above.
123
124       ·  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
128          derived metric) and the optional condition  is  the  keyword  exists
129          (true  if metric exists, i.e. is defined in the PMNS) or the keyword
130          values (true if metric exists in the PMNS and has one or  more  cur‐
131          rent values) 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
139          If the condition is missing, the default is exists.
140
141          When  an  explicit  condition  is  provided,  there  may  also be an
142          optional state_rule of the form
143                               ? true_state : false_state
144          where true_state (applies if  condition  is  true)  and  false_state
145          (applies  if  condition  is  false) are both taken from the keywords
146          include (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
152          The default state_rule is
153                                 ? available : exclude
154
155       ·  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
159       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

OPTIONS

165       The available command line options are:
166
167       -c   Enable non-interactive, auto-create mode.
168
169       -d groupdir, --groups=groupdir
170            Specify the path to the groupsdir directory.
171
172       -g grouptag, --group=grouptag
173            Query logging state for the specific logging group named grouptag.
174
175       -h host, --host=host
176            Performance  metrics source is pmcd(1) on host, rather than on the
177            default localhost.
178
179       -q, --quiet
180            Quiet mode, suppress logging interval dialog.
181
182       -r, --reprobe
183            Reconsider every group for inclusion in the configfile.
184
185       -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
188            retired pmlogconf-setup shell script from earlier versions of PCP.
189
190       -v, --verbose
191            Enable verbose mode.
192
193       -?, --help
194            Display usage message and exit.
195

EXAMPLE

197       The following group file demonstrates all of  the  supported  syntactic
198       elements.
199
200       #pmlogconf-setup 2.0
201       ident   Example group file
202       ident   ... more description
203       delta   1 minute
204       probe   sample.secret.foo.one values ? include : exclude
205               sample.secret.foo.one
206               sample.secret.foo.bar   # non-leaf in the PMNS
207               sample.colour [ red green ]
208

MIGRATION

210       The  current  version  of pmlogconf (2.0) supports a slightly different
211       format for configfile compared to earlier versions.  If an old  version
212       configfile  is  presented  to pmlogconf it will be converted to the new
213       format.
214

PCP ENVIRONMENT

216       Environment variables with the prefix PCP_ are used to parameterize the
217       file  and  directory names used by PCP.  On each installation, the file
218       /etc/pcp.conf contains the  local  values  for  these  variables.   The
219       $PCP_CONF  variable may be used to specify an alternative configuration
220       file, as described in pcp.conf(5).
221
222       pmlogconf overrides any $PCP_DERIVED_CONFIG environment variable to  an
223       empty string, for performance reasons.
224
225       pmlogconf  honours  the  $PMCD_WAIT_TIMEOUT  environment  variable when
226       probing and creating new  pmlogger  configuration  files.   It  uses  a
227       default  timeout  value  of  10  seconds for this, in the absence of an
228       environment setting.
229

SEE ALSO

231       pmcd(1), pmlogger(1), pcp.conf(5) and pcp.env(5).
232
233
234
235Performance Co-Pilot                  PCP                         PMLOGCONF(1)
Impressum