'\"macro stdmacro
.\"
.\" Copyright (c) 2000-2004 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMTRACE 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmtrace\f1 \- command line performance instrumentation
.SH SYNOPSIS
\f3pmtrace\f1
[\f3-q?\f1]
[\f3\-c\f1 \f2value\f1 | \f3\-e\f1 \f2command\f1 | \f3\-v\f1 \f2value\f1]
[\f3\-h\f1 \f2host\f1]
[\f3\-S\f1 \f2state\f1]
\f2tag\f1
.SH DESCRIPTION
.B pmtrace
provides a simple command line interface to the trace Performance Metrics Domain
Agent (PMDA) and the associated \f2pcp_trace\f1 library.
.PP
The default
.B pmtrace
behavior is to provide point trace data to the trace PMDA, using the
.I tag
argument as the identifying name associated with each trace point.
The
.I tag
then becomes an instance identifier within the set of trace.point metrics.
.SH OPTIONS
The available command line options are:
.TP 5
\fB\-c\fR \fIvalue\fR
Allow an arbitrary counter \f2value\f1 to be exported through
the trace.count metrics.
.TP
\fB\-e\fR \fIcommand\fR
Allow an arbitrary \f2command\f1 to be executed.
This \f2command\f1 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.
.TP
\fB\-h\fR \fIhost\fR
Sent the trace data to the trace PMDA running on
.IR host ,
rather than the localhost.
This overrides use of the environment variable
.BR PCP_TRACE_HOST .
.TP
\fB\-q\fR
Suppress messages from a successful trace, so that
.B pmtrace
runs quietly.
.TP
\fB\-S\fR \fIstate\fR
Enable internal debugging and tracing.
The value of
.I state
is a bit-wise combination of debug flags as defined in
.BR pmtracestate (3),
and may be specified using the decimal or hexadecimal syntax prescribed
by
.BR strtol (3).
.TP
\fB\-v\fR \fIvalue\fR
Allow an arbitrary floating point \f2value\f1 to be exported through
the trace.observe metrics.
.TP
\fB\-?\fR
Display usage message and exit.
.SH DIAGNOSTICS
All are generated on standard error and are intended to be self-explanatory.
.PP
The
.B pmtrace
exit status is always zero except when the
.B \-e
option is in use, in which case the exit status of \f2command\f1 is returned.
.SH FILES
.TP 5
.BI $PCP_DEMOS_DIR/trace/pmtrace.c
source code for
.B pmtrace
.SH ENVIRONMENT
Since
.B pmtrace
uses the \f2libpcp_trace\f1 library routines, the environment variables
\f3PCP_TRACE_HOST\f1, \f3PCP_TRACE_PORT\f1, and \f3PCP_TRACE_TIMEOUT\f1
are all honored.
Refer to
.BR pmdatrace (3)
for a detailed description of the semantics of each.
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.SH SEE ALSO
.BR pmcd (1),
.BR pmdatrace (1),
.BR pmprobe (1),
.BR PMAPI (3)
and
.BR pmdatrace (3).