Product SiteDocumentation Site

4.7.4. Configuring the Trace Library

The trace library is configurable through the use of environment variables listed in Table 4.5, “Environment Variables” as well as through the state flags listed in Table 4.6, “State Flags”. Both provide diagnostic output and enable or disable the configurable functionality within the library.

Table 4.5. Environment Variables

Name
Description
PCP_TRACE_HOST
The name of the host where the trace PMDA is running.
PCP_TRACE_PORT
TCP/IP port number on which the trace PMDA is accepting client connections.
PCP_TRACE_TIMEOUT
The number of seconds to wait until assuming that the initial connection is not going to be made, and timeout will occur. The default is three seconds.
PCP_TRACE_REQTIMEOUT
The number of seconds to allow before timing out on awaiting acknowledgment from the trace PMDA after trace data has been sent to it. This variable has no effect in the asynchronous trace protocol (refer to Table 4.6, “State Flags”).
PCP_TRACE_RECONNECT
A list of values which represents the backoff approach that the libpcp_trace library routines take when attempting to reconnect to the trace PMDA after a connection has been lost. The list of values should be a positive number of seconds for the application to delay before making the next reconnection attempt. When the final value in the list is reached, that value is used for all subsequent reconnection attempts.
The Table 4.6, “State Flags” are used to customize the operation of the libpcp_trace routines. These are registered through the pmtracestate call, and they can be set either individually or together.

Table 4.6. State Flags

Flag
Description
PMTRACE_STATE_NONE
The default. No state flags have been set, the fault-tolerant, synchronous protocol is used for communicating with the trace PMDA, and no diagnostic messages are displayed by the libpcp_trace routines.
PMTRACE_STATE_API
High-level diagnostics. This flag simply displays entry into each of the API routines.
PMTRACE_STATE_COMMS
Diagnostic messages related to establishing and maintaining the communication channel between application and PMDA.
PMTRACE_STATE_PDU
The low-level details of the trace protocol data units (PDU) is displayed as each PDU is transmitted or received.
PMTRACE_STATE_PDUBUF
The full contents of the PDU buffers are dumped as PDUs are transmitted and received.
PMTRACE_STATE_NOAGENT
Interprocess communication control. If this flag is set, it causes interprocess communication between the instrumented application and the trace PMDA to be skipped. This flag is a debugging aid for applications using libpcp_trace.
PMTRACE_STATE_ASYNC
Asynchronous trace protocol. This flag enables the asynchronous trace protocol so that the application does not block awaiting acknowledgment PDUs from the trace PMDA. In order for the flag to be effective, it must be set before using the other libpcp_trace entry points.