Product SiteDocumentation Site

4.7. Trace API

The libpcp_trace Application Programming Interface (API) is called from C, C++, Fortran, and Java. Each language has access to the complete set of functionality offered by libpcp_trace. In some cases, the calling conventions differ slightly between languages. This section presents an overview of each of the different tracing mechanisms offered by the API, as well as an explanation of their mappings to the actual performance metrics exported by the trace PMDA.

4.7.1. Transactions

Paired calls to the pmtracebegin and pmtraceend API functions result in transaction data being sent to the trace PMDA with a measure of the time interval between the two calls. This interval is the transaction service time. Using the pmtraceabort call causes data for that particular transaction to be discarded. The trace PMDA exports transaction data through the following trace.transact metrics listed in Table 4.2, “ trace.transact Metrics”:

Table 4.2.  trace.transact Metrics

Metric
Description
trace.transact.ave_time
The average service time per transaction type. This time is calculated over the last sample duration.
trace.transact.count
The running count for each transaction type seen since the trace PMDA started.
trace.transact.max_time
The maximum service time per transaction type within the last sample duration.
trace.transact.min_time
The minimum service time per transaction type within the last sample duration.
trace.transact.rate
 
The average rate at which each transaction type is completed. The rate is calculated over the last sample duration.
trace.transact.total_time
The cumulative time spent processing each transaction since the trace PMDA started running.