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(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 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.