PMEVENT(1)PMEVENT(1)NAMEpmevent - report event record details
SYNOPSISpmevent [-gLz] [-a archive] [-h host] [-K spec] [-O offset] [-p port]
[-S starttime] [-s samples] [-T endtime] [-t interval] [-x pattern] [-Z
timezone] metricname ...
DESCRIPTION
Performance Co-Pilot (PCP) supports event records within the framework
for fetching general performance information. pmevent prints current
or archived values for the nominated event record metrics. The event
records of interest are contained in one or more of the metrics identi‐
fied by the metricname arguments.
Unless directed to another host by the -h option, or to an archive by
the -a option or to a local context by the -L option, pmevent will con‐
tact the Performance Metrics Collector Daemon (PMCD) on the local host
to obtain the required information. The -a,-h and -L options are mutu‐
ally exclusive.
The metricname arguments may be given in the metric specification syn‐
tax, as described in PCPIntro(1), where the source and metric name may
all be included in the metricname, e.g.
thathost:someagent.event.records or
myarchive/someagent.event.records['foo-instance','bar-instance']. When
this format is used, any of the -h or -a or -L options may also be
specified, provided the usage is consistent in terms of the source of
the metrics identified by the options as compared to any explicit
source of the metrics defined in the metricname arguments.
When using the metric specification syntax, the ``hostname'' @ is
treated specially and causes pmevent to use a local context to collect
metrics from PMDAs on the local host without PMCD (same as the -L
option). Only some metrics are available in this mode.
The -S, -T and -O options may be used to define a time window to
restrict the samples retrieved, set an initial origin within the time
window; refer to PCPIntro(1) for a complete description of these
options.
When processing an archive, pmevent may relinquish its own timing con‐
trol, and operate as a ``slave'' of a pmtime(1) process that uses a GUI
dialog to provide timing control. In this case, either the -g option
should be used to start pmevent as the sole slave of a new pmtime(1)
instance, or -p should be used to attach pmevent to an existing
pmtime(1) instance via the IPC channel identified by the port argument.
The other options that control the information reported by pmevent are
as follows:
-a Performance metric values are retrieved from the PCP archive log
file identified by the base name archive.
-g Start pmevent as the slave of a new pmtime(1) process for replay
of archived performance data using the pmtime(1) graphical user
interface.
-h Current performance metric values are retrieved from the nominated
host machine.
-K When fetching metrics from a local context, the -K option may be
used to control the DSO PMDAs that should be made accessible. The
spec argument conforms to the syntax described in __pmSpecLocalP‐
MDA(3). More than one -K option may be used.
-L Causes pmevent to use a local context to collect metrics from
PMDAs on the local host without PMCD. Only some metrics are
available in this mode.
-p Attach pmevent to an existing pmtime(1) time control process
instance via the IPC channel identified by the port argument.
This option is normally only used by other tools, e.g.
pmchart(1), when they launch pmevent with synchronized time con‐
trol.
-s The argument samples defines the number of samples to be retrieved
and reported. If samples is 0 or -s is not specified, pmevent
will sample and report continuously (in real time mode) or until
the end of the PCP archive (in archive mode).
It is not possible to control the number of event records, as each
value of a metricname may deliver zero, one or more event records.
The -s option determines how many times pmevent will retrieve val‐
ues for the specified metricname metrics.
-t The default sampling interval may be set to something other than
the default 1 second. The interval argument follows the syntax
described in PCPIntro(1), and in the simplest form may be an
unsigned integer (the implied units in this case are seconds).
For PCP archives, pmevent will retrieve all of the event records
for the metricname metrics within the requested time window, so
the value of the sampling interval will have no effect in this
case.
-x The given filter is sent to the performance metric domain agent
for the requested metricname before any values are requested.
This serves two purposes. Firstly, it provides a mechanism for
server-side event filtering that is customisable for individual
event streams. In addition, some performance metrics domain
agents also use the PMCD store mechanism to provide a basic secu‐
rity model (e.g. for sensitive log files, only a client host with
pmStore(3) access would be able to access the event stream).
-Z By default, pmevent reports the time of day according to the local
timezone on the system where pmevent is run. The -Z option
changes the timezone to timezone in the format of the environment
variable TZ as described in environ(5).
-z Change the reporting timezone to the local timezone at the host
that is the source of the performance metrics, as identified via
either the metricname or the -h or -a or -L options.
The output from pmevent is directed to standard output.
SEE ALSOPCPIntro(1), pmcd(1), pmchart(1), pmdumplog(1), pminfo(1), pmlogger(1),
pmtime(1), pmval(1), PMAPI(3), __pmSpecLocalPMDA(3), pcp.conf(4) and
pcp.env(4).
DIAGNOSTICS
All are generated on standard error and are intended to be self-
explanatory.
Performance Co-Pilot PMEVENT(1)
