1PMTRACE(3)                 Library Functions Manual                 PMTRACE(3)
2
3
4

NAME

6       pmtracebegin,   pmtraceend,   pmtraceabort,  pmtracepoint,  pmtraceobs,
7       pmtracecounter, pmtracestate, pmtraceerrstr - application-level perfor‐
8       mance instrumentation services
9

C SYNOPSIS

11       #include <pcp/trace.h>
12
13       int pmtracebegin(const char *tag);
14       int pmtraceend(const char *tag);
15       int pmtraceabort(const char *tag);
16       int pmtracepoint(const char *tag);
17       int pmtraceobs(const char *tag, double value);
18       int pmtracecounter(const char *tag, double value);
19       char *pmtraceerrstr(int code);
20       int pmtracestate(int flags);
21
22       cc ... -lpcp_trace
23

FORTRAN SYNOPSIS

25       character*(*) tag
26       integer code
27       integer flags
28       integer state
29       character*(*) estr
30       real*8 value
31
32       code = pmtracebegin(tag)
33       code = pmtraceend(tag)
34       code = pmtraceabort(tag)
35       code = pmtracepoint(tag)
36       code = pmtraceobs(tag, value)
37       code = pmtracecounter(tag, value)
38       pmtraceerrstr(code, estr)
39       state = pmtracestate(flags)
40
41       f77 ... -lpcp_trace  or  f90 ... -lpcp_trace
42

JAVA SYNOPSIS

44       import sgi.pcp.trace;
45
46       int trace.pmtracebegin(String tag);
47       int trace.pmtraceend(String tag);
48       int trace.pmtraceabort(String tag);
49       int trace.pmtracepoint(String tag);
50       int trace.pmtraceobs(String tag, double value);
51       int trace.pmtracecounter(String tag, double value);
52       String trace.pmtraceerrstr(int code);
53       int trace.pmtracestate(int flags);
54
55

DESCRIPTION

57       The  pcp_trace  library  functions  provide a mechanism for identifying
58       sections of a program as transactions or events for use  by  the  trace
59       Performance Metrics Domain Agent (refer to pmdatrace(1) and PMDA(3)).
60
61       The monitoring of transactions using the Performance Co-Pilot (PCP) in‐
62       frastructure is initiated through a call to pmtracebegin.  Time will be
63       recorded  from  the  end  of each pmtracebegin call to the start of the
64       following call to pmtraceend, where the same tag identifier is used  in
65       both calls.  Following from this, no visible recording will occur until
66       at least one call to pmtraceend is made referencing  a  tag  previously
67       used in a call to pmtracebegin.
68
69       A  transaction which is currently in progress can be cancelled by call‐
70       ing pmtraceabort.  No transaction data  gathered  for  that  particular
71       transaction  will  be  exported, although data from previous and subse‐
72       quent successful transactions with that tag name  are  still  exported.
73       This  is  most useful when an error condition arises during transaction
74       processing and the transaction does not run to completion.
75
76       The tag argument to pmtracebegin, pmtraceend and pmtraceabort  is  used
77       to  uniquely identify each transaction within the pcp_trace library and
78       later by the trace PMDA as the  instance  domain  identifiers  for  the
79       transaction  performance  metrics which it exports.  These routines are
80       most useful when used around blocks of code which are likely to be exe‐
81       cuted  a  number  of  times over some relatively long time period (in a
82       daemon process, for example).
83
84       pmtracebegin has two distinct roles - firstly as the initiator of a new
85       transaction,  and secondly as a mechanism for setting a new start time.
86       Similarly, pmtraceend is used to register a new  tag  and  its  initial
87       state  with  the  trace PMDA, or alternatively to update the statistics
88       which the PMDA currently associates with the given tag.
89
90       A second form of program instrumentation can be obtained from  pmtrace‐
91       point.   This  is  a  simpler form of monitoring as it exports only the
92       number of times that a particular point in a program has  been  passed.
93       This  differs to the transaction monitoring offered by pmtracebegin and
94       pmtraceend, which exports a running  count  of  successful  transaction
95       completions  as  well  as  statistics  on the time interval between the
96       start and end points of each transaction.  This function is most useful
97       when start and end points are not well defined.  Examples of this would
98       be when the code branches in such a way that a  transaction  cannot  be
99       clearly  identified, or when processing does not follow a transactional
100       model, or the desired instrumentation is akin  to  event  rates  rather
101       than event service times.
102
103       The  pmtraceobs  and pmtracecounter functions have similar semantics to
104       pmtracepoint, but also allow an arbitrary numeric value to be passed to
105       the trace PMDA.  The most recent value for each tag is then immediately
106       available from the PMDA.  The only difference  between  pmtraceobs  and
107       pmtracecounter is that the value exported via pmtracecounter is assumed
108       to be a monotonically increasing counter  value  (e.g.  the  number  of
109       bytes  read  from  a socket), whereas the value exported via pmtraceobs
110       can be any value at all.
111
112       pmtracestate allows the application to set state flags which  are  hon‐
113       oured by subsequent calls to the pcp_trace library routines.  There are
114       currently two types of flag - debugging flags and the asynchronous pro‐
115       tocol flag.  A single call may specify a number of flags together, com‐
116       bined using a (bitwise) logical OR operation, and overrides the  previ‐
117       ous state setting.
118
119       The debugging flags to pmtracestate cause pcp_trace to print diagnostic
120       messages on the standard output stream at important processing  points.
121       The  default  protocol  used  between  the  trace  PMDA  and individual
122       pcp_trace client applications is a synchronous protocol,  which  allows
123       for  dropped  connections  to  be reestablished at a later stage should
124       this become possible.  An asynchronous protocol is also available which
125       does  not provide the reconnection capability, but which does away with
126       much of the overhead inherent in synchronous communication.   This  be‐
127       haviour  can be toggled using the pmtracestate call, but must be called
128       before other calls to the library.  This differs to the debugging state
129       behaviour,  which can be altered at any time.  pmtracestate returns the
130       previous state (setting prior to being called).
131
132       The following table describes each of the pmtracestate flags - examples
133       of  the  use of these flags in each supported language are given in the
134       demo applications (refer to the ``FILES'' section below).
135
136            ┌────────────┬───────────────────────────────────────────────┐
137            │State Flags │                   Semantics                   │
138            ├────────────┼───────────────────────────────────────────────┤
139            │0  NONE     │ Synchronous PDUs and no diagnostics (default) │
140            │1  API      │ Shows processing just below the API (debug)   │
141            │2  COMMS    │ Shows network-related activity (debug)        │
142            │4  PDU      │ Shows app<->PMDA IPC traffic (debug)          │
143            │8  PDUBUF   │ Shows internal IPC buffer management (debug)  │
144            │16 NOAGENT  │ No PMDA communications at all (debug)         │
145            │32 ASYNC    │ Use the asynchronous PDU protocol (control)   │
146            └────────────┴───────────────────────────────────────────────┘
147       Should any of the pcp_trace library functions return a negative  value,
148       an  error  has  occurred.   This  can  be  diagnosed  further using the
149       pmtraceerrstr routine, which takes the negative  return  value  as  its
150       code argument, and in the C-callable interface returns a pointer to the
151       associated error message.  This points into a static error  table,  and
152       should therefore not be passed to free(3).  The Fortran-callable inter‐
153       face has a slightly different syntax, requiring the destination charac‐
154       ter  array  to  be passed in as the second argument.  The Java-callable
155       interface returns a UTF-8 string, created using the  JNI  (Java  Native
156       Interface) routine NewStringUTF.
157

ENVIRONMENT

159       The  pcp_trace  routines  communicate  with the trace PMDA via a socket
160       connection, which by default uses TCP/IP port number 4323.  This can be
161       over-ridden  by  setting PCP_TRACE_PORT to a different port number when
162       the application is started.  The host where the trace PMDA  is  running
163       is   by   default   the  localhost,  but  this  can  be  changed  using
164       PCP_TRACE_HOST.  When attempting to connect to  a  remote  trace  PMDA,
165       after  some specified time interval has elapsed, the connection attempt
166       will be aborted and an error status  will  be  returned.   The  default
167       timeout  interval  is  3  seconds,  and this can be modified by setting
168       PCP_TRACE_TIMEOUT in the environment to a real number  of  seconds  for
169       the  desired  timeout.   This  is most useful in cases where the remote
170       host is at the end of a slow network,  requiring  longer  latencies  to
171       establish the connection correctly.
172

NOTES

174       The  pcp_trace  Java  class  interface  has been developed and verified
175       using version 1.1 of the Java Native Interface (JNI) specification.
176

FILES

178       $PCP_DEMOS_DIR/trace/*.c
179                 Sample C programs and source for pmtrace(1).  Use make(1)  to
180                 build these programs.
181
182       $PCP_DEMOS_DIR/trace/fapp1.f
183                 Sample  Fortran program.  Call `make fortran77' or `make for‐
184                 tran90' to build this program.
185
186       $PCP_DEMOS_DIR/trace/japp1.java
187                 Sample Java program.  `make java' builds the java class file.
188
189       /usr/java/classes/sgi/pcp/trace.java
190                 Java trace class definition.
191

PCP ENVIRONMENT

193       Environment variables with the prefix PCP_ are used to parameterize the
194       file  and  directory names used by PCP.  On each installation, the file
195       /etc/pcp.conf contains the  local  values  for  these  variables.   The
196       $PCP_CONF  variable may be used to specify an alternative configuration
197       file, as described in pcp.conf(5).  Values for these variables  may  be
198       obtained programmatically using the pmGetConfig(3) function.
199

SEE ALSO

201       file:$PCP_DOC_DIR/Tutorial/trace.html,  pcp.man.tutorial, Provided the,
202       make(1), pmcd(1), pmdatrace(1), pmprobe(1), pmtrace(1), Relevant infor‐
203       mation  is also available from the on-line PCP Tutorial, subsystem from
204       the PCP images has been installed, access the URL  and  from  your  web
205       browser.
206

DIAGNOSTICS

208       A  negative  return  value  from a pcp_trace function indicates that an
209       error has occurred - if this is the  case,  the  return  value  can  be
210       passed to pmtraceerrstr to obtain the associated error message.
211
212       Success is indicated by a return value of zero.
213
214       pmtracestate also returns an integer representing the state flags which
215       were set prior to the call.
216

CAVEAT

218       Applications that use gethostbyname(3) should exercise caution  because
219       the  static  fields  in struct hostent may not be preserved across some
220       pcp_trace calls.  In  particular,  pmtracebegin,  pmtraceend,  pmtrace‐
221       point,  pmtracecounter,  and  pmtraceobs  may all call gethostbyname(3)
222       internally.
223
224
225
226Performance Co-Pilot                  PCP                           PMTRACE(3)
Impressum