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);

       The  pcp_trace  library  functions provide a mechanism for
       identifying 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 refer­
       encing a tag previously used in a call to pmtracebegin.

       A  transaction  which is currently in progress can be can­
       celled by calling pmtraceabort.  No transaction data gath­
       ered  for  that  particular  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  arises  during
       transaction processing and the transaction does not run to
       completion.

       The tag argument to pmtracebegin, pmtraceend and  pmtrace­
       abort is used to uniquely identify each transaction within
       the pcp_trace library and later by the trace PMDA  as  the
       instance  domain  identifiers  for the transaction perfor­
       mance 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  relatively  long
       time period (in a daemon process, for example).

       pmtracebegin  has two distinct roles - firstly as the ini­
       tiator 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  update the statistics
       which the PMDA currently associates with the given tag.

       A second form of program instrumentation can  be  obtained
       from  pmtracepoint.   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 branches in such a way  that  a  transaction
       cannot  be clearly identified, or when processing does not
       follow a transactional model, or the desired  instrumenta­
       tion  is  akin  to  event  rates rather than event service


       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 between pmtraceobs and
       pmtracecounter  is  that  the  value exported via pmtrace­
       counter  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, com­
       bined using a (bitwise) logical OR  operation,  and  over­
       rides the previous state setting.

       The  debugging  flags  to  pmtracestate cause pcp_trace to
       print diagnostic messages on the standard output stream at
       important  processing  points.   The default protocol used
       between the trace PMDA  and  individual  pcp_trace  client
       applications  is  a synchronous protocol, which allows for
       dropped connections to be reestablished at a  later  stage
       should  this become possible.  An asynchronous protocol is
       also available which does  not  provide  the  reconnection
       capability,  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 - examples of the use of these flags  in  each  sup­
       ported  language are given in the demo applications (refer
       to the ``FILES'' section below).
+-------------------------+-----------------------------------------------+
|      State Flags        |                   Semantics                   |
+-------------------------+-----------------------------------------------+
|0  PMTRACE_STATE_NONE    | Synchronous PDUs and no diagnostics (default) |
|1  PMTRACE_STATE_API     | Shows processing just below the API (debug)   |
|2  PMTRACE_STATE_COMMS   | Shows network-related activity (debug)        |
|4  PMTRACE_STATE_PDU     | Shows app<->PMDA IPC traffic (debug)          |
|8  PMTRACE_STATE_PDUBUF  | Shows internal IPC buffer management (debug)  |
|16 PMTRACE_STATE_NOAGENT | No PMDA communications at all (debug)         |
|32 PMTRACE_STATE_ASYNC   | Use the asynchronous PDU protocol (control)   |
+-------------------------+-----------------------------------------------+
       Should any of the pcp_trace  library  functions  return  a
       negative  value,  an  error  has  occured.   This  can  be

       takes  the negative return value as its code argument, and
       in the C-callable interface returns a pointer to the asso­
       ciated  error  message.   This  points into a static error
       table, and should therefore not be passed to free(3).  The
       Fortran-callable  interface  has a slightly different syn­
       tax, 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 NewStringUTF.


ENVIRONMENT

       The pcp_trace routines communicate with the trace PMDA via
       a socket 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  appli­
       cation  is started.  The host where the trace PMDA is run­
       ning is by default the localhost, but this can be  changed
       using  PCP_TRACE_HOST.   When  attempting  to connect to a
       remote 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 inter­
       val  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 useful in
       cases where the remote host is at the end of a  slow  net­
       work,  requiring longer latencies to establish the connec­
       tion correctly.


NOTES

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


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.


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

       may  be used to specify an alternative configuration file,
       as described in pcp.conf(4).  Values for  these  variables
       may  be  obtained programatically using the pmGetConfig(3)
       function.


SEE ALSO

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


DIAGNOSTICS

       A  negative  return  value from a pcp_trace function indi­
       cates that an error has occured - 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.


CAVEAT

       Applications  that  use  gethostbyname(3N) should exercise
       caution because the static fields in  struct  hostent  may
       not be preserved across some pcp_trace calls.  In particu­
       lar,  pmtracebegin,  pmtraceend,  pmtracepoint,   pmtrace­
       counter,  and  pmtraceobs  may  all call gethostbyname(3N)
       internally.


Man(1) output converted with man2html