NAME

       pmtrace - command line performance instrumentation

SYNOPSIS

       pmtrace [-q?]  [-c value | -e command | -v value] [-h host] [-S state] tag

DESCRIPTION

       pmtrace  provides  a simple command line interface to the trace Performance Metrics Domain
       Agent (PMDA) and the associated pcp_trace library.

       The default pmtrace behavior is to provide point trace data to the trace PMDA,  using  the
       tag  argument  as  the  identifying  name  associated with each trace point.  The tag then
       becomes an instance identifier within the set of trace.point metrics.

OPTIONS

       The available command line options are:

       -c value
            Allow an arbitrary counter value to be exported through the trace.count metrics.

       -e command
            Allow an arbitrary command to be executed.   This  command  will  be  measured  as  a
            transaction  since it has well defined start and end points.  The information is made
            available through the trace.transact metrics.

       -h host
            Sent the trace data to the trace PMDA running on host,  rather  than  the  localhost.
            This overrides use of the environment variable PCP_TRACE_HOST.

       -q   Suppress messages from a successful trace, so that pmtrace runs quietly.

       -S state
            Enable  internal debugging and tracing.  The value of state is a bit-wise combination
            of debug flags as defined in pmtracestate(3), and may be specified using the  decimal
            or hexadecimal syntax prescribed by strtol(3).

       -v value
            Allow  an  arbitrary  floating  point  value to be exported through the trace.observe
            metrics.

       -?   Display usage message and exit.

DIAGNOSTICS

       All are generated on standard error and are intended to be self-explanatory.

       The pmtrace exit status is always zero except when the -e option is in use, in which  case
       the exit status of command is returned.

FILES

       $PCP_DEMOS_DIR/trace/pmtrace.c
            source code for pmtrace

ENVIRONMENT

       Since   pmtrace   uses  the  libpcp_trace  library  routines,  the  environment  variables
       PCP_TRACE_HOST,  PCP_TRACE_PORT,  and  PCP_TRACE_TIMEOUT  are  all  honored.    Refer   to
       pmdatrace(3) for a detailed description of the semantics of each.

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

SEE ALSO

       pmcd(1), pmdatrace(1), pmprobe(1), PMAPI(3) and pmdatrace(3).