... assorted routines ...
This description presents an overview of the PMAPI and the context in which PMAPI applications are run. The PMAPI is more fully described in the Performance Co-Pilot Programmer's Guide, and the manual pages for the individual PMAPI routines.
Not all PMIDs need be represented in the PMNS of every application. For example, an application which monitors disk traffic will likely use a name space which references only the PMIDs for I/O statistics.
Applications which use the PMAPI may have independent versions of a PMNS, constructed from an initialization file when the application starts; see pmLoadASCIINameSpace(3), pmLoadNameSpace(3), pmnscomp(1) and pmns(4).
Internally (below the PMAPI) the implementation of the Performance Metrics Collection System (PMCS) uses only the PMIDs, and a PMNS provides an external mapping from a hierarchic taxonomy of names to PMIDs that is convenient in the context of a particular system or particular use of the PMAPI. For the applications programmer, the routines pmLookupName(3) and pmNameID(3) translate between names in a PMNS and PMIDs, and vice versa. The PMNS may be traversed using pmGetChildren(3).
Contexts are identified by a ``handle'', a small integer value that is returned when the context is created; see pmNewContext(3) and pmDupContext(3). Some PMAPI functions require an explicit ``handle'' to identify the correct context, but more commonly the PMAPI function is executed in the ``current'' context. The current context may be discovered using pmWhichContext(3) and changed using pmUseContext(3).
If a PMAPI context has not been explicitly established (or the previous current context has been closed using pmDestroyContext(3)) then the current PMAPI context is undefined.
In addition to the source of the performance metrics, the context also includes the instance profile and collection time (both described below) which controls how much information is returned, and when the information was collected.
The instances are identified by an internal identifier assigned by the agent responsible for instantiating the values for the associated performance metric. Each instance identifier has a corresponding external instance identifier name (an ASCII string). The routines pmGetInDom(3), pmLookupInDom(3) and pmNameInDom(3) may be used to enumerate all instance identifiers, and to translate between internal and external instance identifiers.
All of the instance identifiers for a particular performance metric are collectively known as an instance domain. Multiple performance metrics may share the same instance domain.
If only one instance is ever available for a particular performance metric, the instance identifier in the result from pmFetch(3) assumes the special value PM_IN_NULL and may be ignored by the application, and only one instance-value pair appears in the result for that metric. Under these circumstances, the associated instance domain (as returned via pmLookupDesc(3)) is set to PM_INDOM_NULL to indicate that values for this metric are singular.
The difficult issue of transient performance metrics (e.g. per-filesystem information, hot-plug replaceable hardware modules, etc.) means that repeated requests for the same PMID may return different numbers of values, and/or some changes in the particular instance identifiers returned. This means applications need to be aware that metric instantiation is guaranteed to be valid at the time of collection only. Similar rules apply to the transient semantics of the associated metric values. In general however, it is expected that the bulk of the performance metrics will have instantiation semantics that are fixed over the execution life-time of any PMAPI client.
The type field in the pmDesc structure returned by pmLookupDesc(3) identifies the format and type of the values for a particular performance metric within a particular PMAPI context.
Note that the encoding of values for a particular performance metric may be different for different PMAPI contexts, due to differences in the underlying implementation for different contexts. However it is expected that the vast majority of performance metrics will have consistent value encoding across all versions of all implementations, and hence across all PMAPI contexts.
The PMAPI supports routines to automate the handling of the various value formats and types, particularly for the common case where conversion to a canonical format is desired, see pmExtractValue(3) and pmPrintValue(3).
The routine pmConvScale(3) is provided to convert values in conjunction with the pmUnits structures that defines the dimensionality and scale of the values for a particular performance metric as returned from pmFetch(3), and the desired dimensionality and scale of the value the PMAPI client wishes to manipulate.
The routines pmAddProfile(3) and pmDelProfile(3) may be used to dynamically adjust the instance profile.
There is an issue here of exactly when individual metrics may have been collected, especially given their origin in potentially different Performance Metric Domains, and variability in the metric updating frequency at the lowest level of the Performance Metric Domain. The PMCS opts for the pragmatic approach, in which the PMAPI implementation undertakes to return all of the metrics with values accurate as of the timestamp, to the best of our ability. The belief is that the inaccuracy this introduces is small, and the additional burden of accurate individual timestamping for each returned metric value is neither warranted nor practical (from an implementation viewpoint).
Of course, in the case of collection of metrics from multiple hosts the PMAPI client must assume the sanity of the timestamps is constrained by the extent to which clock synchronization protocols are implemented across the network.
A PMAPI application may call pmSetMode(3) to vary the requested collection time, e.g. to rescan performance metrics values from the recent past, or to ``fast-forward'' through an archive log.
Where the size of a result is known at the time of a call, it is the caller's responsibility to allocate (and possibly free) the storage, and the called function will assume the result argument is of an appropriate size. Where a result is of variable size and that size cannot be known in advance (e.g. for pmGetChildren(3), pmGetInDom(3), pmNameInDom(3), pmNameID(3), pmLookupText(3) and pmFetch(3)) the PMAPI implementation uses a range of dynamic allocation schemes in the called routine, with the caller responsible for subsequently releasing the storage when no longer required. In some cases this simply involves calls to free(3C), but in others (most notably for the result from pmFetch(3)), special routines (e.g. pmFreeResult(3)) should be used to release the storage.
As a general rule, if the called routine returns an error status then no allocation will have been done, and any pointer to a variable sized result is undefined.
The PMAPI routine pmErrStr(3) translates error conditions into error messages. By convention, the small negative values are assumed to be negated versions of the Unix error codes as defined in <errno.h> and the strings returned are as per strerror(3C). The larger, negative error codes are PMAPI error conditions.
One error, common to all PMAPI routines that interact with pmcd(1) on some host is PM_ERR_IPC, which indicates the communication link to pmcd(1) has been lost.