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.