Product SiteDocumentation Site

3.3. Current PMAPI Context

When performance metrics are retrieved across the PMAPI, they are delivered in the context of a particular source of metrics, a point in time, and a profile of desired instances. This means that the application making the request has already negotiated across the PMAPI to establish the context in which the request should be executed.
A metric's source may be the current performance data from a particular host (a live or real-time source), or a set of archive logs of performance data collected by pmlogger at some remote host or earlier time (a retrospective or archive source). The metric's source is specified when the PMAPI context is created by calling the pmNewContext function. This function returns an opaque handle which can be used to identify the context.
The collection time for a performance metric is always the current time of day for a real-time source, or current position for an archive source. For archives, the collection time may be set to an arbitrary time within the bounds of the set of archive logs by calling the pmSetMode function.
The last component of a PMAPI context is an instance profile that may be used to control which particular instances from an instance domain should be retrieved. When a new PMAPI context is created, the initial state expresses an interest in all possible instances, to be collected at the current time. The instance profile can be manipulated using the pmAddProfile and pmDelProfile functions.
The current context can be changed by passing a context handle to pmUseContext. If a live context connection fails, the pmReconnectContext function can be used to attempt to reconnect it.