src/include/pcp/trace.h

   1 /*
   2  * Copyright (c) 1997 Silicon Graphics, Inc.  All Rights Reserved.
   3  *
   4  * This library is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU Lesser General Public License as published
   6  * by the Free Software Foundation; either version 2.1 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful, but
  10  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  11  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
  12  * License for more details.
  13  */
  14 #ifndef PCP_TRACE_H
  15 #define PCP_TRACE_H
  16
  17 /*
  18  * Transaction monitoring PMDA (trace) public interface.
  19  *
  20  * An example program using this interface can be found at
  21  * $PCP_DEMOS_DIR/trace/demo.c and contains further doumentation.
  22  * Also refer to the pmdatrace(1) and pmdatrace(3) man pages and
  23  * the Performance Co-Pilot Programmer's Guide.
  24  */
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /*
  31  * Add a new entry to the table of transactions currently being monitored,
  32  * or update an existing entry.
  33  */
  34 extern int pmtracebegin(const char *);
  35
  36 /*
  37  * Make measurements recorded for the given transaction tag available
  38  * through the trace PMDA.
  39  */
  40 extern int pmtraceend(const char *);
  41
  42 /*
  43  * Cancel a transaction which began from an earlier call to pmtracebegin,
  44  * without exporting new data through the trace PMDA.
  45  */
  46 extern int pmtraceabort(const char *);
  47
  48 /*
  49  * An alternate form of measurement can be obtained using pmtracepoint.
  50  * This is a count-only measurement, and will result in the trace PMDA
  51  * exporting the number of times a given code point is passed (ie. the
  52  * the number of times a particular label has been passed to pmtracepoint.
  53  */
  54 extern int pmtracepoint(const char *);
  55
  56 /*
  57  * An extension to pmtracepoint is pmtraceobs, with similar semantics to
  58  * pmtracepoint except allowing an arbitrary numeric value (double) to be
  59  * exported up through the PMAPI.
  60  */
  61 extern int pmtraceobs(const char *, double);
  62
  63 /*
  64  * Similar to pmtraceobs is pmtracecounter, with the only difference
  65  * being the way the trace PMDA exports the given numeric value to
  66  * PMAPI clients (exported with counter semantics, rather than with
  67  * instantaneous semantics which is the case with pmtraceobs).
  68  */
  69 extern int pmtracecounter(const char *, double);
  70
  71 /*
  72  * Should any of these routines return a negative value, the return value
  73  * can be passed to pmtraceerrstr for the associated error message.
  74  * This performs a lookup into a static error message table, so the returned
  75  * pointer must not be freed.
  76  */
  77 extern char *pmtraceerrstr(int);
  78
  79 #define PMTRACE_ERR_BASE        12000
  80 #define PMTRACE_ERR_TAGNAME     (-PMTRACE_ERR_BASE-0)
  81 #define PMTRACE_ERR_INPROGRESS  (-PMTRACE_ERR_BASE-1)
  82 #define PMTRACE_ERR_NOPROGRESS  (-PMTRACE_ERR_BASE-2)
  83 #define PMTRACE_ERR_NOSUCHTAG   (-PMTRACE_ERR_BASE-3)
  84 #define PMTRACE_ERR_TAGTYPE     (-PMTRACE_ERR_BASE-4)
  85 #define PMTRACE_ERR_TAGLENGTH   (-PMTRACE_ERR_BASE-5)
  86 #define PMTRACE_ERR_IPC         (-PMTRACE_ERR_BASE-6)
  87 #define PMTRACE_ERR_ENVFORMAT   (-PMTRACE_ERR_BASE-7)
  88 #define PMTRACE_ERR_TIMEOUT     (-PMTRACE_ERR_BASE-8)
  89 #define PMTRACE_ERR_VERSION     (-PMTRACE_ERR_BASE-9)
  90 #define PMTRACE_ERR_PERMISSION  (-PMTRACE_ERR_BASE-10)
  91 #define PMTRACE_ERR_CONNLIMIT   (-PMTRACE_ERR_BASE-11)
  92
  93 /*
  94  * Diagnostic and state switching
  95  */
  96 extern int pmtracestate(int code);
  97
  98 #define PMTRACE_STATE_NONE    0  /* default: synchronous and no diagnostics */
  99 #define PMTRACE_STATE_API     1  /* debug:   processing just below the API  */
 100 #define PMTRACE_STATE_COMMS   2  /* debug:   shows network-related activity */
 101 #define PMTRACE_STATE_PDU     4  /* debug:   shows app<->PMDA IPC traffic   */
 102 #define PMTRACE_STATE_PDUBUF  8  /* debug:   internal IPC buffer management */
 103 #define PMTRACE_STATE_NOAGENT 16 /* debug:   no PMDA communications at all  */
 104 #define PMTRACE_STATE_ASYNC   32 /* control: use asynchronous PDU protocol  */
 105
 106 #ifdef __cplusplus
 107 }
 108 #endif
 109
 110 #endif /* PCP_TRACE_H */