The mandatory argument archive is the base name for the physical files that constitute an archive log.
The -V option specifies whether a version 1 or version 2 archive is generated. A version 2 archive also stores the associated Performance Metrics Name Space (PMNS). By default a version 2 archive is generated.
Unless directed to another host by the -h option, pmlogger will contact the Performance Metrics Collector Daemon (PMCD) on the local host and use that as the source of the metric values to be logged.
To support the required flexibility and control over what is logged and when, pmlogger maintains an independent two level logging state for each instance of each performance metric. At the first (mandatory) level, logging is allowed to be on (with an associated interval between samples), or off or maybe. In the latter case, the second (advisory) level logging is allowed to be on (with an associated interval between samples), or off.
The mandatory level allows universal specification that some metrics must be logged, or must not be logged. The default state for all instances of all metrics when pmlogger starts is mandatory maybe and advisory off.
Use pmlc(1) to interrogate and change the logging state once pmlogger is running.
If a metric's state is mandatory (on or off) and a request is made to change it to mandatory maybe, the new state is mandatory maybe and advisory off. If a metric's state is already advisory (on or off) and a request is made to change it to mandatory maybe, the current state is retained.
It is not possible for pmlogger to log specific instances of a metric and all instances of the same metric concurrently. If specific instances are being logged and a request to log all instances is made, then all instances of the metric will be logged according to the new request, superseding any prior logging request for the metric. A request to log all instances of a metric will supersede any previous request to log all instances. A request to log specific instances of a metric when all instances are already being logged is refused. To do this one must turn off logging for all instances of the metric first. In each case, the validity of the request is checked first; for example a request to change a metric's logging state to advisory on when it is currently mandatory off is never permitted (it is necessary to change the state to mandatory maybe first).
Optionally, each system running pmcd(1) may also be configured to run a ``primary'' pmlogger instance. Like pmcd(1), this pmlogger instance is launched by $PCP_RC_DIR/pcp, and is affected by the files /etc/config/pmlogger (use chkconfig(1M) to activate or disable the primary pmlogger instance), /etc/config/pmlogger.options (command line options passed to the primary pmlogger) and $PCP_VAR_DIR/config/pmlogger/config.default (the default initial configuration file for the primary pmlogger).
The primary pmlogger instance is identified by the -P option. There may be at most one ``primary'' pmlogger instance on each system with an active pmcd(1). The primary pmlogger instance (if any) must be running on the same host as the pmcd(1) to which it connects, so the -h and -P options are mutually exclusive.
When launched as a non-primary instance, pmlogger will exit immediately if the configuration file causes no metric logging to be scheduled. The -L option overrides this behavior, and causes a non-primary pmlogger instance to ``linger'', presumably pending some future dynamic re-configuration and state change via pmlc(1). pmlogger will also linger without the -L option being used if all the metrics to be logged are logged as once only metrics. When the once only metrics have been logged, a warning message will be generated stating that the event queue is empty and no more events will be scheduled.
By default all diagnostics and errors from pmlogger are written to the file pmlogger.log in the directory where pmlogger is launched. The -l option may be used to override the default behavior. If the log file cannot be created or is not writable, output is written to standard error instead.
If specified, the -s option instructs pmlogger to terminate after a certain size in records, bytes or time units has been accumulated. If endsize is an integer then endsize records will be written to the log. If endsize is suffixed by b or bytes then endsize bytes of the archive data will be written out (note, however, that archive log record boundaries will not be broken and so this limit may be slightly surpassed). Other viable file size units include: K, Kb, Kilobyte for kilobytes and M, Mb, Megabyte for megabytes. These units may be optionally suffixed by an s and may be of mixed case. Alternatively endsize may be suffixed using a time unit as described in PCPIntro(1) for the interval argument (to the standard PCP tool option -t).
Some examples of different formats: -s 100 -s 100bytes -s 100K -s 100Mb -s 10mins -s 10hoursThe default is for pmlogger to run forever.
The -r option causes the size of the physical record(s) for each group of metrics and the expected contribution of the group to the size of the PCP archive for one full day of collection to be reported in the log file. This information is reported the first time each group is successfully written to the archive.
The log file is potentially a multi-volume data set, and the -v option causes pmlogger to start a new volume after a certain size in records, bytes, or time units has been accumulated for the current volume. The format of this size specification is identical to that of the -s option (see above). The default is for pmlogger to create a single volume log. Additional volume switches can also be forced asynchronously by either using pmlc(1) or sending pmlogger a SIGHUP signal (see below). Note, if a scheduled volume switch is in operation due to the -v option, then its counters will be reset after an asynchronous switch.
Normally pmlogger operates on the distributed Performance Metrics Name Space (PMNS), however if the -n option is specified an alternative local PMNS is loaded from the file pmnsfile.
Under normal circumstances, pmlogger will run forever (except for a -s option or a termination signal). The -T option may be used to limit the execution time using the format of time as prescribed by PCPIntro(1).
Some examples of different formats: -T 10mins -T '@ 11:30'From this it can be seen that -T 10mins and -s 10mins perform identical actions.
When pmlogger receives a SIGHUP signal, the current volume of the log is closed, and a new volume is opened. This mechanism (or the alternative mechanism via pmlc(1)) may be used to manage the growth of the log files - once a log volume is closed, that file may be archived without ill-effect on the continued operation of pmlogger. See also the -v option above.
The buffers for the current log may be flushed to disk using the flush command of pmlc(1), or by sending pmlogger a SIGUSR1 signal or by using the -u option (the latter forces every log write to be unbuffered). This is useful when the log needs to be read while pmlogger is still running.
When launched with the -x option, pmlogger will accept asynchronous control requests on the file descriptor fd. This option is only expected to be used internally by PCP applications that support ``live record mode''.
If configfile does not exist, then a search is made in the directory $PCP_VAR_DIR/config/pmlogger for a file of the same name, and if found that file is used, e.g. if config.mumble does not exist in the current directory and the file $PCP_VAR_DIR/config/pmlogger/config.mumble does exist, then -c config.mumble and -c $PCP_VAR_DIR/config/pmlogger/config.mumble are equivalent.
The syntax for the configuration file is as follows.
Internal limitations require the interval to be smaller than (approximately) 74 hours. An interval value of zero is a synonym for once. An interval of default means to use the default logging interval of 60 seconds; this default value may be changed to interval with the -t command line option.
If no instances are given, then the logging specification is applied to all instances of the associated metric.
The base operations are advisory, mandatory and enquire. In all other aspects, these access control statements follow the syntactic and semantic rules defined for the access control mechanisms used by PMCD and are fully documented in pmcd(1).
The following is a simple default configuration file for a primary pmlogger instance, and demonstrates most of the capabilities of the configuration specification language.
log mandatory on once { hinv.ncpu hinv.ndisk }
log mandatory on every 10 minutes {
disk.all.write
disk.all.read
network.interface.in.packets [ "et0" ]
network.interface.out.packets [ "et0" ]
nfs.server.reqs [ "lookup" "getattr" "read" "write" ]
}
log advisory on every 30 minutes {
environ.temp
pmcd.pdu_in.total
pmcd.pdu_out.total
}
[access]
disallow * : all except enquire;
allow localhost : mandatory, advisory;
For example, changing $PCP_RC_DIR/pcplocal so that it contains:
'start') # Add startup actions here ($PCP_BINADM_DIR/pmlogger_check &) ;; 'stop') # Add shutdown actions here ($PCP_BINADM_DIR/pmsignal -a -s TERM pmlogger &) ;;
will start pmlogger instances at boot time and terminate them in an orderly fashion at system shutdown.
This script runs as root, so any pmlogger instances it launches are also run as root. To run some pmlogger instances as a particular user, create your own archive logger control file (see pmlogger_check(1)) and use the su(1) command. e.g.
'start') # Add startup actions here (su tanya -c "$PCP_BINADM_DIR/pmlogger_check -c /usr/people/tanya/ctl" &) ;;
at boot time will start the pmlogger instances described in /usr/people/tanya/ctl, running as user tanya.
There may be at most one primary
pmlogger
instance per monitored host; attempting to bend this rule produces the error:
pmlogger: there is already a primary pmlogger running
Various other messages relating to the creation and/or deletion of files in $PCP_TMP_DIR/pmlogger suggest a permission problem on this directory, or some feral files have appeared therein.