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] [-h host] configfile
10

DESCRIPTION

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

SETUP GROUP FILES

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
67       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
73       These group files are processed in the following ways:
74
75       ·  When a new configfile is created, all group files are processed.
76
77       ·  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
81       ·  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
86       ·  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
91       ·  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
98       Each group file is structured as follows:
99
100       ·  The first line must contain #pmlogconf-setup 2.0
101
102       ·  Other lines beginning with # are treated as comments.
103
104       ·  Blank lines are ignored.
105
106       ·  One or more lines starting with the keyword ident are used  to  pro‐
107          vide the human-readable description of the group.
108
109       ·  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
116       ·  A control line starting with one of the keywords probe or force must
117          be present.
118
119       ·  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
123       ·  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
138          If the condition is missing, the default is exists.
139
140          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
151          The default state_rule is
152                                 ? available : exclude
153
154       ·  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
158       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

OPTIONS

164       The available command line options are:
165
166       -c   Enable non-interactive, auto-create mode.
167
168       -d groupdir, --groups=groupdir
169            Specify the path to the groupsdir directory.
170
171       -h host, --host=host
172            Performance metrics source is pmcd(1) on host, rather than on  the
173            default localhost.
174
175       -q, --quiet
176            Quiet mode, suppress logging interval dialog.
177
178       -r, --reprobe
179            Reconsider every group for inclusion in the configfile.
180
181       -v, --verbose
182            Enable verbose mode.
183
184       -?, --help
185            Display usage message and exit.
186

EXAMPLE

188       The  following  group  file demonstrates all of the supported syntactic
189       elements.
190
191       #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

MIGRATION

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

PCP ENVIRONMENT

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
213       pmlogconf  overrides any $PCP_DERIVED_CONFIG environment variable to an
214       empty string, for performance reasons.
215
216       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

SEE ALSO

222       pmcd(1), pmlogger(1), pcp.conf(5) and pcp.env(5).
223
224
225
226Performance Co-Pilot                  PCP                         PMLOGCONF(1)
Impressum