Man Linux: Main Page and Category List

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 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 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 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 pmtraceabort 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 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 relatively 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  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 transaction.  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 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 between 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 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 supported language are given in the
       demo applications (refer to the ‘‘FILES’’ section below).

            +------------+-----------------------------------------------+
            |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  occured.   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 static 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 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 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  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  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 useful in cases where the remote
       host is at the end of a slow network,  requiring  longer  latencies  to
       establish the connection 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  local  values  for  these variables.  The
       $PCP_CONF variable 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  indicates  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    particular,   pmtracebegin,   pmtraceend,
       pmtracepoint,   pmtracecounter,   and   pmtraceobs   may    all    call
       gethostbyname(3N) internally.