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.

       The -e option allows 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.

       Trace data can be sent to the trace PMDA running on host, rather than the localhost, using
       the -h option.  This overrides use of the environment variable PCP_TRACE_HOST.

       The -q option suppresses messages from a successful trace, so that pmtrace runs quietly.

       The  -c  option  allows  an arbitrary counter value to be exported through the trace.count
       metrics, while the -v option allows an arbitrary  floating  point  value  to  be  exported
       through the trace.observe metrics

       The  -S  option  enables 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).

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.

FILES

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

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

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.