1PMDATRACE(1)                General Commands Manual               PMDATRACE(1)
2
3
4

NAME

6       pmdatrace  -  application-level  transaction performance metrics domain
7       agent
8

SYNOPSIS

10       $PCP_PMDAS_DIR/trace/pmdatrace [-d domain] [-l logfile] [-A access] [-I
11       port] [-M username] [-N buckets] [-T period] [-U units]
12

DESCRIPTION

14       pmdatrace  is  a  Performance Metrics Domain Agent (PMDA) which exports
15       transaction performance metrics from application  processes  which  use
16       the pcp_trace library described in pmdatrace(3).
17
18       A brief description of the pmdatrace command line options follows:
19
20       -d   It  is absolutely crucial that the performance metrics domain num‐
21            ber specified here is unique  and  consistent.   That  is,  domain
22            should  be  different for every PMDA on the one host, and the same
23            domain number should be used for the same PMDA on all hosts.
24
25       -l   Location of the log file.  By default, a log file named  trace.log
26            is  written  in the current directory of pmcd(1) when pmdatrace is
27            started, i.e.  $PCP_LOG_DIR/pmcd.  If the log file cannot be  cre‐
28            ated  or  is not writable, output is written to the standard error
29            instead.
30
31       -A   Host-based access control for pmdatrace.  access must be either an
32            allow  or deny specification, using either allow:hostspec:maxconns
33            or disallow:hostspec, where `allow' and `disallow'  are  keywords,
34            `hostspec'  is  a host specification conforming to the format used
35            by both pmcd(1) and pmlogger(1), and  `maxconns'  is  the  maximum
36            number  of  connections  allowed from a given `hostspec'.  Using a
37            maximum connections of zero specifies an unlimited number of  con‐
38            nections for the accompanying `hostspec'.
39
40       -I   Communicate  with  pcp_trace  clients via the given Internet port.
41            This can alternatively be specified by setting $PCP_TRACE_PORT  in
42            the  environment  to  some valid port number (use of the -I option
43            overrides this).  The default port number is 4323.
44
45       -T   period defines the aggregation period used to compute  the  recent
46            averages and extrema.  Specified as a time interval using the syn‐
47            tax described in PCPIntro(1) for the common -t PCP argument,  e.g.
48            30 seconds or 1 min.  The default is 60 seconds.
49
50       -M   User  account  under  which  to run the agent.  The default is the
51            unprivileged "pcp" account in current  versions  of  PCP,  but  in
52            older versions the superuser account ("root") was used by default.
53
54       -N   Internally,  the  aggregation  period is divided into bucket divi‐
55            sions, and the rolling average is recomputed  every  period/bucket
56            seconds.  For example, the defaults correspond to -T 60 and -N 12,
57            which means the average is recomputed every  five  seconds  for  a
58            period covering the prior 60 seconds.
59
60       -U   This  option  allows  the  dimension and scale associated with the
61            observation value metric to be configured.  units is a comma-sepa‐
62            rated string of six integer values, which are the space dimension,
63            time dimension, count dimension,  space  scale,  time  scale,  and
64            count  scale,  respectively.   The  default dimension and scale is
65            ``none'', which is equivalent to presenting ``0,0,0,0,0,0'' as the
66            argument  to -U.  The units associated with a metric are most eas‐
67            ily viewed using the -d (metric description) option to  pminfo(1).
68            The Install script described below steps through this option quite
69            explicitly, so it is recommended that the Install script  be  used
70            for building up the units specification.
71
72       Essentially,  the  exported  metrics provide statistics on the time for
73       completion of each transaction, and an average  count  of  transactions
74       completed and watch points passed over a given time period.
75

INSTALLATION

77       In  order  for a host to export the names, help text and values for the
78       Trace performance metrics, do the following as root:
79
80            # cd $PCP_PMDAS_DIR/trace
81            # ./Install
82
83       If you want to undo the installation, do the following as root:
84
85            # cd $PCP_PMDAS_DIR/trace
86            # ./Remove
87
88       pmdatrace is launched by pmcd(1) and should never be executed directly.
89       The  Install  and  Remove  scripts  notify  pmcd(1)  when  the agent is
90       installed or removed.
91

FILES

93       $PCP_PMCDCONF_PATH
94                 command line options used to launch pmdatrace
95       $PCP_PMDAS_DIR/trace/help
96                 default help text file for the trace metrics
97       $PCP_DEMOS_DIR/trace/*
98                 example programs which use the pcp_trace library
99       $PCP_PMDAS_DIR/trace/Install
100                 installation script for the pmdatrace agent
101       $PCP_PMDAS_DIR/trace/Remove
102                 undo installation script for pmdatrace
103       $PCP_LOG_DIR/pmcd/trace.log
104                 default log file for error  messages  and  other  information
105                 from pmdatrace
106

PCP ENVIRONMENT

108       Environment variables with the prefix PCP_ are used to parameterize the
109       file and directory names used by PCP.  On each installation,  the  file
110       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
111       $PCP_CONF variable may be used to specify an alternative  configuration
112       file, as described in pcp.conf(5).
113

SEE ALSO

115       PCPIntro(1), pmcd(1), pmtrace(1), PMAPI(3) and pmdatrace(3).
116
117
118
119Performance Co-Pilot                  PCP                         PMDATRACE(1)
Impressum