'\" t
'\"macro stdmacro
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\" Copyright (c) 2011 Ken McDonell.  All Rights Reserved.
.\" Copyright (c) 2011 Nathan Scott.  All Rights Reserved.
.\" 
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\" 
.\"
.TH PMEVENT 1 "" "Performance Co-Pilot"
.SH NAME
\f3pmevent\f1 \- report event record details
.SH SYNOPSIS
\f3pmevent\f1
[\f3\-gLz\f1]
[\f3\-a\f1 \f2archive\f1]
[\f3\-h\f1 \f2host\f1]
[\f3\-K\f1 \f2spec\f1]
[\f3\-O\f1 \f2offset\f1]
[\f3\-p\f1 \f2port\f1]
[\f3\-S\f1 \f2starttime\f1]
[\f3\-s\f1 \f2samples\f1]
[\f3\-T\f1 \f2endtime\f1]
[\f3\-t\f1 \f2interval\f1]
[\f3\-x\f1 \f2pattern\f1]
[\f3\-Z\f1 \f2timezone\f1]
\f2metricname\f1 ...
.SH DESCRIPTION
.de EX
.in +0.5i
.ie t .ft CB
.el .ft B
.ie t .sp .5v
.el .sp
.ta \\w' 'u*8
.nf
..
.de EE
.fi
.ie t .sp .5v
.el .sp
.ft R
.in
..
Performance Co-Pilot (PCP) supports event records within the framework
for fetching general performance information.
.B 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
.I metricname
arguments.
.PP
Unless directed to another host by the
.B \-h
option,
or to an archive by the
.B \-a
option
or to a local context by the
.B \-L
option,
.B pmevent
will contact the Performance Metrics Collector Daemon (PMCD)
on the local host to obtain the required information.
The
.BR \-a , \-h
and
.B \-L
options are mutually exclusive.
.PP
The
.I metricname
arguments may be given in the metric specification syntax, as
described in
.BR PCPIntro (1),
where the source and metric name may all be included in the
.IR metricname ,
e.g. thathost:someagent.event.records
or
myarchive/someagent.event.records['foo-instance','bar-instance'].
When this format is used, any of the
.B \-h
or
.B \-a
or
.B \-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
.I metricname
arguments.
.PP
When using the metric specification syntax, the ``hostname''
.B @
is treated specially and
causes
.B pmevent
to use a local context to collect metrics from PMDAs on the local host
without PMCD (same as the
.B \-L
option).  Only some metrics are available in this mode.
.PP
The
.BR \-S ,
.BR \-T
and
.BR \-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
.BR PCPIntro (1)
for a complete description of these options.
.PP
When processing an archive,
.B pmevent
may relinquish its own timing control, and operate as a ``slave'' of a
.BR pmtime (1)
process that uses a GUI dialog to provide timing control.
In this case, either the
.B \-g
option should be used to start
.B pmevent
as the sole slave of a new
.BR pmtime (1)
instance, or
.B \-p
should be used to attach
.B pmevent
to an existing
.BR pmtime (1)
instance via the IPC channel identified by the
.I port
argument.
.PP
The other options that control the information reported by
.B pmevent
are as follows:
.TP 5
.B \-a
Performance metric values are retrieved from the PCP
archive log file identified by the base name
.IR archive .
.TP
.B \-g
Start
.B pmevent
as the slave of a new
.BR pmtime (1)
process for replay of archived performance data using the
.BR pmtime (1)
graphical user interface.
.TP
.B \-h
Current performance metric values are retrieved from the nominated
.I host
machine.
.TP
.B \-K
When
fetching metrics from a local context, the
.B \-K
option may be used to control the DSO PMDAs that should be
made accessible.  The
.I spec
argument conforms to the syntax described in
.BR __pmSpecLocalPMDA (3).
More than one
.B \-K
option may be used.
.TP
.B \-L
Causes
.B 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.
.TP
.B \-p
Attach
.B pmevent
to an existing
.BR pmtime (1)
time control process instance via the IPC channel identified by the
\f2port\f1 argument.
This option is normally only used by other tools, e.g.
.BR pmchart (1),
when they launch
.B pmevent
with synchronized time control.
.TP
.B \-s
The argument
.I samples
defines the number of samples to be retrieved and reported.
If
.I samples
is 0 or
.B \-s
is not specified, 
.B pmevent
will sample and report continuously (in real time mode) or until the end
of the PCP archive (in archive mode).
.RS
.PP
It is not possible to control the number of event records, as each
value of a
.I metricname
may deliver zero, one or more event records.  The
.B \-s
option determines how many times
.I pmevent
will retrieve values for the specified
.I metricname
metrics.
.RE
.TP
.B \-t
The default sampling \f2interval\f1 may be set to something other than the
default 1 second.
The
.I interval
argument follows the syntax described in
.BR PCPIntro (1),
and in the simplest form may be an unsigned integer (the implied
units in this case are seconds).
.RS
.PP
For PCP archives,
.I pmevent
will retrieve
.B all
of the event records for the
.I metricname
metrics within the requested time window, so the value of the
sampling interval will have no effect in this case.
.RE
.TP
.B \-x
The given
.I filter
is sent to the performance metric domain agent for the requested
.I 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
.BR pmStore (3)
access would be able to access the event stream).
.RE
.TP
.B \-Z
By default,
.B pmevent
reports the time of day according to the local timezone on the
system where
.B pmevent
is run.
The
.B \-Z
option changes the timezone to
.I timezone
in the format of the environment variable
.B TZ
as described in
.BR environ (5).
.TP
.B \-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
.I metricname
or the
.B \-h
or
.B \-a
or
.B \-L
options.
.PP
The output from
.B pmevent
is directed to standard output.
.SH SEE ALSO
.BR PCPIntro (1),
.BR pmcd (1),
.BR pmchart (1),
.BR pmdumplog (1),
.BR pminfo (1),
.BR pmlogger (1),
.BR pmtime (1),
.BR pmval (1),
.BR PMAPI (3),
.BR __pmSpecLocalPMDA (3),
.BR pcp.conf (5)
and
.BR pcp.env (5).
.SH DIAGNOSTICS
All are generated on standard error and are intended to be self-explanatory.