# pmdatrace

## NAME



           **pmtracebegin** , **pmtraceend** , **pmtraceabort** , **pmtracepoint** , **pmtraceobs** ,
           **pmtracecounter** , **pmtracestate** , **pmtraceerrstr** - application-level
           performance instrumentation services
    


## C SYNOPSIS



           **#include <pcp/trace.h>**
    
           **int pmtracebegin(const char ***_tag_**);**
           **int pmtraceend(const char ***_tag_**);**
           **int pmtraceabort(const char ***_tag_**);**
           **int pmtracepoint(const char ***_tag_**);**
           **int pmtraceobs(const char ***_tag_**, double** _value_**);**
           **int pmtracecounter(const char ***_tag_**, double** _value_**);**
           **char *pmtraceerrstr(int** _code_**);**
           **int pmtracestate(int** _flags_**);**
    
           **cc ... -lpcp_trace**
    


## FORTRAN SYNOPSIS



           **character*(*)**_tag_
           **integer** _code_
           **integer** _flags_
           **integer** _state_
           **character*(*)**_estr_
           **real*8** _value_
    
           _code_ **= pmtracebegin(**_tag_**)**
           _code_ **= pmtraceend(**_tag_**)**
           _code_ **= pmtraceabort(**_tag_**)**
           _code_ **= pmtracepoint(**_tag_**)**
           _code_ **= pmtraceobs(**_tag_**,**_value_**)**
           _code_ **= pmtracecounter(**_tag_**,**_value_**)**
           **pmtraceerrstr(**_code_**,**_estr_**)**
           _state_ **= pmtracestate(**_flags_**)**
    
           **f77 ... -lpcp_trace** or  **f90 ... -lpcp_trace**
    


## JAVA SYNOPSIS



           **import sgi.pcp.trace;**
    
           **int trace.pmtracebegin(String** _tag_**);**
           **int trace.pmtraceend(String** _tag_**);**
           **int trace.pmtraceabort(String** _tag_**);**
           **int trace.pmtracepoint(String** _tag_**);**
           **int trace.pmtraceobs(String** _tag_**, double** _value_**);**
           **int trace.pmtracecounter(String** _tag_**, double** _value_**);**
           **String trace.pmtraceerrstr(int** _code_**);**
           **int trace.pmtracestate(int** _flags_**);**
    


## DESCRIPTION



           The  _pcp_trace_ library functions provide a mechanism for identify‐
           ing sections of a program as transactions or events for use by the
           trace Performance Metrics Domain Agent (refer to pmdatrace(1)  and
           PMDA(3)).
    
           The  monitoring  of  transactions  using  the Performance Co-Pilot
           (PCP) infrastructure is initiated through a call to  **pmtracebegin**.
           Time  will  be  recorded from the end of each **pmtracebegin** call to
           the start of the following call to **pmtraceend** , where the same  _tag_
           identifier is used in both calls.  Following from this, no visible
           recording will occur until at least one call to **pmtraceend** is made
           referencing a _tag_ previously used in a call to **pmtracebegin**.
    
           A  transaction  which is currently in progress can be cancelled by
           calling **pmtraceabort**.  No transaction data gathered for that  par‐
           ticular  transaction will be exported, although data from previous
           and subsequent successful transactions  with  that  _tag_  name  are
           still exported.  This is most useful when an error condition aris‐
           es  during transaction processing and the transaction does not run
           to completion.
    
           The _tag_ argument to **pmtracebegin** , **pmtraceend** and  **pmtraceabort** is
           used  to  uniquely  identify each transaction within the _pcp_trace_
           library and later by the trace PMDA as the instance domain identi‐
           fiers for the transaction performance metrics  which  it  exports.
           These  routines  are  most  useful when used around blocks of code
           which are likely to be executed a number of times over some  rela‐
           tively long time period (in a daemon process, for example).
    
           **pmtracebegin** has two distinct roles - firstly as the initiator of
           a new transaction, and secondly as a mechanism for setting  a  new
           start  time.   Similarly, **pmtraceend** is used to register a new _tag_
           and its initial state with the trace PMDA, or alternatively to up‐
           date the statistics which the PMDA currently associates  with  the
           given _tag_.
    
           A  second form of program instrumentation can be obtained from **pm‐**
           **tracepoint**.  This is a simpler form of monitoring  as  it  exports
           only  the number of times that a particular point in a program has
           been passed.  This differs to the transaction  monitoring  offered
           by  **pmtracebegin** and **pmtraceend** , which exports a running count of
           successful transaction completions as well as  statistics  on  the
           time  interval  between  the start and end points of each transac‐
           tion.  This function is most useful when start and end points  are
           not well defined.  Examples of this would be when the code branch‐
           es  in such a way that a transaction cannot be clearly identified,
           or when processing does not follow a transactional model,  or  the
           desired  instrumentation  is akin to event rates rather than event
           service times.
    
           The **pmtraceobs** and **pmtracecounter** functions have similar semantics
           to **pmtracepoint** , but also allow an arbitrary numeric _value_  to  be
           passed  to  the trace PMDA.  The most recent _value_ for each _tag_ is
           then immediately available from the PMDA.  The only difference be‐
           tween **pmtraceobs** and **pmtracecounter** is that the value exported via
           **pmtracecounter** is assumed to be a monotonically increasing counter
           value (e.g. the number of bytes read from a socket),  whereas  the
           value exported via **pmtraceobs** can be any value at all.
    
           **pmtracestate** allows  the application to set state _flags_ which are
           honoured by subsequent calls to the  _pcp_trace_  library  routines.
           There  are  currently  two types of flag - debugging flags and the
           asynchronous protocol flag.  A single call may specify a number of
           _flags_ together, combined using a (bitwise) logical  OR  operation,
           and overrides the previous state setting.
    
           The debugging flags to **pmtracestate** cause _pcp_trace_ to print diag‐
           nostic  messages  on  the standard output stream at important pro‐
           cessing points.  The default protocol used between the trace  PMDA
           and individual _pcp_trace_ client applications is a synchronous pro‐
           tocol, which allows for dropped connections to be reestablished at
           a later stage should this become possible.  An asynchronous proto‐
           col  is also available which does not provide the reconnection ca‐
           pability, but which does away with much of the  overhead  inherent
           in synchronous communication.  This behaviour can be toggled using
           the  **pmtracestate** call,  but must be called before other calls to
           the library.  This differs to the debugging state behaviour, which
           can be altered at any time.   **pmtracestate** returns  the  previous
           state (setting prior to being called).
    
           The following table describes each of the **pmtracestate** _flags_ - ex‐
           amples  of  the  use of these flags in each supported language are
           given in the demo applications (refer to the ``FILES'' section be‐
           low).
            ┌─────────────┬───────────────────────────────────────────────┐
            │ State Flags │                   Semantics                   │
            ├─────────────┼───────────────────────────────────────────────┤
            │ 0  NONE     │ Synchronous PDUs and no diagnostics (default) │
            │ 1  API      │ Shows processing just below the API (debug)   │
            │ 2  COMMS    │ Shows network-related activity (debug)        │
            │ 4  PDU      │ Shows app<->PMDA IPC traffic (debug)          │
            │ 8  PDUBUF   │ Shows internal IPC buffer management (debug)  │
            │ 16 NOAGENT  │ No PMDA communications at all (debug)         │
            │ 32 ASYNC    │ Use the asynchronous PDU protocol (control)   │
            └─────────────┴───────────────────────────────────────────────┘
    
           Should any of the _pcp_trace_ library functions  return  a  negative
           value, an error has occurred.  This can be diagnosed further using
           the  **pmtraceerrstr** routine, which takes the negative return value
           as its _code_ argument, and in the C-callable  interface  returns  a
           pointer to the associated error message.  This points into a stat‐
           ic  error  table,  and  should therefore not be passed to free(3).
           The Fortran-callable interface has a  slightly  different  syntax,
           requiring  the  destination character array to be passed in as the
           second argument.  The  Java-callable  interface  returns  a  UTF-8
           string, created using the JNI (Java Native Interface) routine **New‐**
           **StringUTF**.
    


## NOTES



           The _pcp_trace_ Java class interface has been developed and verified
           using  version  1.1  of the Java Native Interface (JNI) specifica‐
           tion.
    


## CAVEAT



           Applications that use gethostbyname(3) should exercise caution be‐
           cause the static fields in _struct hostent_  may  not  be  preserved
           across  some  _pcp_trace_  calls.   In particular, **pmtracebegin** , **pm‐**
           **traceend** , **pmtracepoint** , **pmtracecounter** ,  and  **pmtraceobs** may  all
           call gethostbyname(3) internally.
    


## DIAGNOSTICS



           A  negative  return value from a _pcp_trace_ function indicates that
           an error has occurred - if this is the case, the return value  can
           be passed to **pmtraceerrstr** to obtain the associated error message.
    
           Success is indicated by a return value of zero.
    
           **pmtracestate** also returns an integer representing the state _flags_
           which were set prior to the call.
    


## FILES



           **$PCP_DEMOS_DIR/trace/*.c**
                  Sample C programs and source for pmtrace(1).  Use make(1)
                  to build these programs.
    
           **$PCP_DEMOS_DIR/trace/fapp1.f**
                  Sample Fortran program.  Call `make fortran77' or `make
                  fortran90' to build this program.
    
           **$PCP_DEMOS_DIR/trace/japp1.java**
                  Sample Java program.  `make java' builds the java class
                  file.
    
           **/usr/java/classes/sgi/pcp/trace.java**
                  Java trace class definition.
    


## ENVIRONMENT



           The _pcp_trace_ routines communicate with the trace PMDA via a sock‐
           et connection, which by default uses TCP/IP port number 4323.
           This can be over-ridden by setting **PCP_TRACE_PORT** to a different
           port number when the application is started.  The host where the
           trace PMDA is running is by default the localhost, but this can be
           changed using **PCP_TRACE_HOST**.  When attempting to connect to a re‐
           mote trace PMDA, after some specified time interval has elapsed,
           the connection attempt will be aborted and an error status will be
           returned.  The default timeout interval is 3 seconds, and this can
           be modified by setting **PCP_TRACE_TIMEOUT** in the environment to a
           real number of seconds for the desired timeout.  This is most use‐
           ful in cases where the remote host is at the end of a slow net‐
           work, requiring longer latencies to establish the connection cor‐
           rectly.
    


## PCP ENVIRONMENT



           Environment variables with the prefix **PCP_** are used to parameter‐
           ize the file and directory names used by PCP.  On each installa‐
           tion, the file _/etc/pcp.conf_ contains the local values for these
           variables.  The **$PCP_CONF** variable may be used to specify an al‐
           ternative configuration file, as described in pcp.conf(5).  Values
           for these variables may be obtained programmatically using the
           pmGetConfig(3) function.
    


* * *