Provided by: pcp_3.10.8build1_amd64 
NAME
pmevent - report event record details
SYNOPSIS
pmevent [-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 identified 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 contact the Performance Metrics Collector Daemon (PMCD) on the local host
to obtain the required information. The -a,-h and -L options are mutually exclusive.
The metricname arguments may be given in the metric specification syntax, 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 control, 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
__pmSpecLocalPMDA(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 control.
-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
values 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 security
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(7).
-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 ALSO
PCPIntro(1), pmcd(1), pmchart(1), pmdumplog(1), pminfo(1), pmlogger(1), pmtime(1), pmval(1), PMAPI(3),
__pmSpecLocalPMDA(3), pcp.conf(5) and pcp.env(5).
DIAGNOSTICS
All are generated on standard error and are intended to be self-explanatory.
Performance Co-Pilot PMEVENT(1)