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

The name of the host where the trace PMDA is running.
TCP/IP port number on which the trace PMDA is accepting client connections.
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.
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”).
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

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.
High-level diagnostics. This flag simply displays entry into each of the API routines.
Diagnostic messages related to establishing and maintaining the communication channel between application and PMDA.
The low-level details of the trace protocol data units (PDU) is displayed as each PDU is transmitted or received.
The full contents of the PDU buffers are dumped as PDUs are transmitted and received.
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.
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.