1 files changed, 309 insertions, 0 deletions
diff --git a/man/man1/pmevent.1 b/man/man1/pmevent.1
new file mode 100644
index 0000000..e8a8ad9
--- /dev/null
+++ b/man/man1/pmevent.1
@@ -0,0 +1,309 @@
+'\"! tbl | mmdoc
+'\"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.