Provided by: libpcp-trace2-dev_5.0.3-1_amd64 bug

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
       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  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(5).   Values  for these variables may be
       obtained programmatically 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 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.

CAVEAT

       Applications that use gethostbyname(3) 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(3) internally.