NAME

       pmlogextract - reduce, extract, concatenate and merge Per­
       formance Co-Pilot archives


SYNOPSIS

       $PCP_BINADM_DIR/pmlogextract  [-wz]  [-c  configfile]  [-n
       pmnsfile]  [-S  starttime]  [-s  samples] [-T endtime] [-v
       volsamples] [-Z timezone] input [...] output

       On IRIX:

       $PCP_BINADM_DIR/pmlogmerge [-z] [-S  starttime]  [-s  sam­
       ples]  [-T  endtime]  [-v  volsamples] [-Z timezone] input
       [...] output


DESCRIPTION

       pmlogextract reads one or more Performance Co-Pilot  (PCP)
       archive  logs identified by input and creates a temporally
       merged and/or reduced PCP  archive  log  in  output.   The
       nature  of  merging  is  controlled by the number of input
       archive logs, while the nature of data reduction  is  con­
       trolled  by the command line arguments.  The input(s) must
       be PCP archive logs created by pmlogger(1).

       pmlogmerge provides a subset of the capabilities of  pmlo­
       gextract,  namely  reading  one  or  more PCP archive logs
       identified by input and creating a temporally  merged  PCP
       archive  log  in  output.  pmlogmerge is deprecated and is
       provided on Irix for backwards-compatibility.

       If only one input is specified, then the default  behavior
       simply  copies  the input PCP archive log, into the output
       PCP archive log.  When two or more PCP  archive  logs  are
       specified  as input, the logs are merged (or concatenated)
       and written to output.


COMMAND LINE OPTIONS

       The command line options for pmlogextract are as follows:

       -c configfile
              Extract only the metrics  specified  in  configfile
              from  the input PCP archive log(s).  The configfile
              syntax accepted by  pmlogextract  is  explained  in
              more  detail  in the Configuration File Syntax sec­
              tion.

       -n pmnsfile
              Normally pmlogextract operates on  the  Performance
              Metrics  Name  Space  (PMNS) from input, however if
              the -n option is  specified  an  alternative  local


       -S starttime
              Define  the  start of a time window to restrict the
              samples retrieved or specify a  ``natural''  align­
              ment  of  the  output sample times; refer to PCPIn­
              tro(1).  See also the -w option.

       -s samples
              The argument samples defines the number of  samples
              to  be written to output.  If samples is 0 or -s is
              not specified, pmlogextract will sample  until  the
              end of the PCP archive, or the end of the time win­
              dow as specified by -T, whichever comes first.  The
              -s  option will override the -T option if it occurs
              sooner.

       -T endtime
              Define the termination of a time window to restrict
              the  samples  retrieved  or  specify  a ``natural''
              alignment of the  output  sample  times;  refer  to
              PCPIntro(1).  See also the -w option.

       The  output archive log is potentially a multi-volume data
       set, and the -v option causes pmlogextract to start a  new
       volume  after  volsamples log records have been written to
       the archive.

       -w     Where -S and -T specify a time  window  within  the
              same  day,  the  -w flag will cause the data within
              the time window to be extracted, for every  day  in
              the archive.  For example, the options -w -S @11:00
              -T @15:00 specify that pmlogextract should  include
              archive  log records only for the periods from 11am
              to 3pm on each day.  When -w is  used,  the  output
              archive  log will contain ``mark'' records to indi­
              cate the temporal discontinuity between the end  of
              one time window and the start of the next.

       -Z timezone
              Use  timezone  when  displaying  the date and time.
              Timezone is in the format of the environment  vari­
              able TZ as described in environ(5).

       -z     Use  the  local timezone of the host from the input
              archive logs.  The default is to initially use  the
              timezone of the local host.

       The  configfile  contains  metrics of interest, listed one
       per line.  Instances may also be specified, but  they  are
       optional.  The format for each metric name is

               metric [[instance[,instance...]]]

       where  metric may be a leaf or a non-leaf node in the Per­
       formance Metrics Namespace (PMNS, see pmns(4)).  If a met­
       ric  refers  to  a non-leaf node in the PMNS, pmlogextract
       will recursively descend the PMNS and include all  metrics
       corresponding  to  descendent  leaf  nodes.  Instances are
       optional, and may be specified as a list of  one  or  more
       space  (or  comma)  separated  names,  numbers or strings.
       Elements in the list that are numbers are  assumed  to  be
       external instance identifiers - see pmGetInDom(3) for more
       information.  If no instances are given, then the  logging
       specification  is  applied to all instances of the associ­
       ated metric(s).


CONFIGURATION FILE EXAMPLE

       This is an example of a valid configfile:

               #
               # config file for pmlogextract
               #

               kernel.all.cpu
               kernel.percpu.cpu.sys ["cpu0","cpu1"]
               disk.dev ["dks0d1"]


FILES

       For each of the input and output archives, several  physi­
       cal files are used.
       archive.meta
                 metadata (metric descriptions, instance domains,
                 etc.) for the archive log
       archive.0 initial volume  of  metrics  values  (subsequent
                 volumes have suffixes 1, 2, ...)
       archive.index
                 temporal index to support rapid random access to
                 the other files in the archive log.


PCP ENVIRONMENT

       Environment variables with the prefix  PCP_  are  used  to
       parameterize the file and directory names used by PCP.  On
       each installation, the  file  /etc/pcp.conf  contains  the
       local  values for these variables.  The $PCP_CONF variable
       may be used to specify an alternative configuration  file,
       as described in pcp.conf(4).


SEE ALSO

       PCPIntro(1),     pmdumplog(1),    pmlc(1),    pmlogger(1),
       pcp.conf(4) and pcp.env(4).

       All error conditions detected by pmlogextract are reported
       on stderr with textual (if sometimes terse) explanation.

       Should  one  of  the input archive logs be corrupted (this
       can happen if the pmlogger instance writing the  log  sud­
       denly  dies), then pmlogextract will detect and report the
       position of the corruption in the file, and any subsequent
       information from that archive log will not be processed.

       If  any  error  is detected, pmlogextract will exit with a
       non-zero status.


CAVEATS

       pmlogmerge has been retained on Irix to provide  backwards
       compatibility  with  earlier PCP releases, however, use of
       pmlogextract is encouraged in  preference  to  pmlogmerge,
       and   pmlogmerge  may  not  be  supported  in  future  PCP
       releases.

       The preamble metrics  (pmcd.pmlogger.archive,  pmcd.pmlog­
       ger.host, and pmcd.pmlogger.port), which are automatically
       recorded by pmlogger at the start of the archive, may  not
       be  present  in the archive output by pmlogextract.  These
       metrics are only relevant while the archive is being  cre­
       ated,  and  have  no  significance once recording has fin­
       ished.


Man(1) output converted with man2html