Scroll to navigation

PMLOGCONF(1) General Commands Manual PMLOGCONF(1)

NAME

pmlogconf - create/edit a pmlogger configuration file

SYNOPSIS

pmlogconf [-cqrvV?] [-d groupsdir] [-g grouptag] [-h host] [-s groupfile] configfile

DESCRIPTION

pmlogconfmay be used to create and modify a generic configuration file forthe PCP archiver,pmlogger(1).

Ifconfigfiledoes not exist,pmlogconfwill create a generic configuration file with adefault set of enabled metrics and logging intervals.

Once created,configfilemay be used with the-coption topmlogger(1)to select performance metrics and specifylogging intervals for a PCP archive.

Ifconfigfiledoes exist,pmlogconfwill prompt for input from the user to enable or disable groupsof related performance metrics and to control the logging intervalfor each enabled group.

Group selection requires a simpley(yes)orn(no) response to the promptLog this group?.

Other responses at this point may be used to selectadditional control functions as follows:

Report the names of the metrics in the current group.
Finish with group selection (quit) and make no further changes tothis group or any subsequent group.
/pattern
Make no change to this group but search for a group containingpatternin the description of the group or the namesof the associated metrics.

A logging interval is specified by responding to theLogging interval?prompt with the keywordsonceordefaultor a validpmlogger(1)interval specification of the form ``everyN timeunits''or simply ``N timeunits ''(theeveryis optional) whereNis an unsigned integer andtimeunitsis one of the keywordsmsec,millisecond,sec,second,min,minute,houror the plural form of one of the keywords.

When run from automated logging setup processes, the-coption is used to indicate thatpmlogconfis in auto-create mode and no interactive dialog takes place.The outputconfigfilehas an additional comment messageand timestamp indicating this fact, so that it can beidentified and subsequently updated using-cagain.This option is not appropriate for interactive use of the tool.

The-qoption suppresses the logging interval dialog and preserves thecurrent interval fromconfigfile.

More verbose output may be enabled with the-voption.

SETUPGROUPFILES

When an initialconfigfileis created, the default specifications come from a set of groupfiles below thegroupsdirspecified with the-doption (the defaultgroupsdiris$PCP_VAR_DIR/config/pmlogconfwhich is most commonly correct, so the-doption is rarely used in practice).

The directory structure belowgroupsdiris arbitrary as all regular files will be found by recursive descent and considered, so add-on productsand PMDA developers can easily extend the available defaults topmlogconfby adding new directories and/or group files belowgroupsdir.

These group files are processed in the following ways:

  • When a newconfigfileis created, all group files are processed.
  • Wheneverpmlogconfis run with an existingconfigfile,groupsdiris traversed to see if any new groups have been defined and should beconsidered for inclusion inconfigfile.
  • Whenpmlogconfprocesses a group inconfigfilethat is enabled, the list of metrics associated with the group istaken from the group file (and replaces any previous list of metricsassociated with this group inconfigfile).
  • When either the-r(reprobe) or the-c(auto-create) command line option is specified, every group (not just newlydiscovered ones) is reprocessed to seeif it should be considered for inclusion inconfigfile.
  • If a group is found inconfigfilebut the corresponding group does not exist belowgroupsdir(as would be the case when a group is made obsolete by a PCP upgrade)then the handling of the group depends on the mode in whichpmlogconfis being run.With-cthe corresponding group is culled fromconfigfile,otherwise the corresponding group is unchanged inconfigfile.In either case a warning is issued.

Each group file is structured as follows:

  • The first line must contain#pmlogconf-setup 2.0
  • Other lines beginning with#are treated as comments.
  • Blank lines are ignored.
  • One or more lines starting with the keywordidentare used to provide the human-readable description of the group.
  • Non-blank lines beginning with white space define metrics to be associatedwith this group, one per line. Each metric specification follows the rulesfor apmlogger(1)configuration, namely either the name of a non-leaf node in the PMNS(implying all descendent names in the PMNS), or the name of a leafnode in the PMNS optionally followed by one or more instance namesenclosed by ``['' and ``]''.
  • A control line starting with one of the keywordsprobeorforcemust be present.
  • An optional logging interval control line begins with thekeyworddeltafollowed by one of thepmlogger(1)interval specification described above.
  • probecontrol lines have the format:


probe metric [condition [state_rule] ]

wheremetricis the name of a PCP metric (must be a leaf node in the PMNS,no instance specification is allowed, and it must not be aderived metric) and the optionalconditionis the keywordexists(true ifmetricexists, i.e. is defined in the PMNS) or the keywordvalues(true ifmetricexists in the PMNS and has one or more current values)or an expression of the form

op val
whereopis one of theawk(1)operators (==, !=, >, >=, <, <=, ~ (regular expression match) or !~ (negated regular expression match)) and valis a value (arbitrary sequence of characters, excluding a space)and theconditionis true if there is some instance ofmetricthat makes the expression true.

If theconditionis missing, the default isexists.

When an explicitconditionis provided, there may also be an optionalstate_ruleof the form

? true_state : false_state
wheretrue_state(applies ifconditionis true) andfalse_state(applies ifconditionis false) are both taken from the keywordsinclude(include and enable the group and the associated metrics inconfigfile),available(include and disable the group inconfigfile- a user action ofyas described above is needed to enable the group andadd the associated metrics intoconfigfile)orexclude(the group is not considered for inclusion inconfigfile).

The defaultstate_ruleis

? available : exclude

•
forcecontrol lines begin with the keywordforcefollowed by one of the states defined above, soone of the actionsinclude,excludeoravailableis applied unconditionally to the group.

Probing is only done when a new group is being added toconfigfileor when the-rcommand line option is specified. The evaluation of the probingconditions is done by contactingpmcd(1)onhostname(defaults to local:).

OPTIONS

The available command line options are:

Enable non-interactive, auto-create mode.
Specify the path to the groupsdir directory.
Query logging state for the specific logging group named grouptag.
Performance metrics source ispmcd(1)onhost,rather than on the default localhost.
Quiet mode, suppress logging interval dialog.
Reconsider every group for inclusion in the configfile.
Report the default logging state for the one logging group in groupfile. This is equivalent output to that produced by the retired pmlogconf-setupshell script from earlier versions of PCP.
Enable verbose mode.
Display version number and exit.
-?, --help
Display usage message and exit.

EXAMPLE

The following group file demonstrates all of the supportedsyntactic elements.

#pmlogconf-setup 2.0
ident   Example group file
ident   ... more description
delta   1 minute
probe   sample.secret.foo.one values ? include : exclude


        sample.secret.foo.one


        sample.secret.foo.bar   # non-leaf in the PMNS


        sample.colour [ red green ]

MIGRATION

The current version ofpmlogconf(2.0)supports a slightly different format forconfigfilecompared to earlier versions. If an old versionconfigfileis presented topmlogconfit will be converted to the new format.

PCPENVIRONMENT

Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the file /etc/pcp.conf contains the local values for these variables. The $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

pmlogconfoverrides any$PCP_DERIVED_CONFIGenvironment variable to an empty string, for performance reasons.

pmlogconfhonours the$PMCD_WAIT_TIMEOUTenvironment variable when probing and creating newpmloggerconfiguration files.It uses a default timeout value of 10 seconds for this, in theabsence of an environment setting.

SEEALSO

pmcd(1),pmlogger(1),pcp.conf(5)andpcp.env(5).

PCP Performance Co-Pilot