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