NAME

       pmdatrace - application-level transaction performance met­
       rics domain agent


SYNOPSIS

       $PCP_PMDAS_DIR/trace/pmdatrace [-d  domain]  [-l  logfile]
       [-A access] [-I port] [-N buckets] [-T period] [-U units]


DESCRIPTION

       pmdatrace  is  a  Performance  Metrics Domain Agent (PMDA)
       which exports transaction performance metrics from  appli­
       cation processes which use the pcp_trace library described
       in pmdatrace(3).

       A brief description of the pmdatrace command line  options
       follows:

       -d   It is absolutely crucial that the performance metrics
            domain number specified here is  unique  and  consis­
            tent.   That is, domain should be different for every
            PMDA on the one host,  and  the  same  domain  number
            should be used for the same PMDA on all hosts.

       -l   Location  of  the  log  file.  By default, a log file
            named trace.log is written in the  current  directory
            of   pmcd(1)   when   pmdatrace   is   started,  i.e.
            $PCP_LOG_DIR/pmcd.  If the log file cannot be created
            or is not writable, output is written to the standard
            error instead.

       -A   Host-based access control for pmdatrace.  access must
            be  either  an  allow  or  deny  specification, using
            either allow:hostspec:maxconns or  disallow:hostspec,
            where `allow' and `disallow' are keywords, `hostspec'
            is a host specification conforming to the format used
            by  both  pmcd(1)  and pmlogger(1), and `maxconns' is
            the maximum number  of  connections  allowed  from  a
            given  `hostspec'.   Using  a  maximum connections of
            zero specifies an unlimited number of connections for
            the accompanying `hostspec'.

       -I   Communicate  with  pcp_trace  clients  via  the given
            Internet port.  This can alternatively  be  specified
            by setting $PCP_TRACE_PORT in the environment to some
            valid port number (use of  the  -I  option  overrides
            this).  The default port number is 4323.

       -T   period defines the aggregation period used to compute
            the recent averages and extrema.  Specified as a time
            interval  using  the  syntax described in PCPIntro(1)
            for the common -t PCP argument, e.g. 30 seconds or  1
            min.  The default is 60 seconds.

            bucket divisions, and the rolling average  is  recom­
            puted  every period/bucket seconds.  For example, the
            defaults correspond to -T 60 and -N 12,  which  means
            the  average  is  recomputed every five seconds for a
            period covering the prior 60 seconds.

       -U   This option allows the dimension and scale associated
            with  the  observation value metric to be configured.
            units is a comma-separated string of six integer val­
            ues,  which  are the space dimension, time dimension,
            count dimension, space scale, time scale,  and  count
            scale, respectively.  The default dimension and scale
            is  ``none'',  which  is  equivalent  to   presenting
            ``0,0,0,0,0,0''  as  the  argument  to -U.  The units
            associated with a metric are most easily viewed using
            the -d (metric description) option to pminfo(1).  The
            Install script described  below  steps  through  this
            option  quite  explicitly,  so it is recommended that
            the Install script be used for building up the  units
            specification.

       Essentially,  the  exported  metrics provide statistics on
       the time for completion of each transaction, and an  aver­
       age  count  of  transactions  completed  and  watch points
       passed over a given time period.


INSTALLATION

       In order for a host to export the  names,  help  text  and
       values for the Trace performance metrics, do the following
       as root:

            # cd $PCP_PMDAS_DIR/trace
            # ./Install

       If you want to undo the installation, do the following  as
       root:

            # cd $PCP_PMDAS_DIR/trace
            # ./Remove

       pmdatrace  is launched by pmcd(1) and should never be exe­
       cuted directly.  The Install  and  Remove  scripts  notify
       pmcd(1) when the agent is installed or removed.


FILES

       $PCP_PMCDCONF_PATH
                 command line options used to launch pmdatrace
       $PCP_PMDAS_DIR/trace/help
                 default help text file for the trace metrics
       $PCP_DEMOS_DIR/trace/*
                 example programs which use the pcp_trace library

                 installation script for the pmdatrace agent
       $PCP_PMDAS_DIR/trace/Remove
                 undo installation script for pmdatrace
       $PCP_LOG_DIR/pmcd/trace.log
                 default log file for error  messages  and  other
                 information from pmdatrace


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),  pmcd(1),  pmtrace(1),  PMAPI(3)  and   pmda­
       trace(3).

       Relevant  information  is  also available from the on-line
       PCP Tutorial.   Provided  the  pcp.man.tutorial  subsystem
       from  the  PCP  images  has been installed, access the URL
       file:$PCP_DOC_DIR/Tutorial/trace.html   from   your    web
       browser.


Man(1) output converted with man2html