# pmtrace

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


* * *