3.8.6. PMAPI Metrics Services
The functions described in this section provide Performance Metrics Application Programming Interface (PMAPI) metrics services.
3.8.6.1. pmFetch Function
int pmFetch(int numpmid, pmID pmidlist[], pmResult **result)
Python:
pmResult* pmresult = pmFetch(c_uint pmid[])
The most common PMAPI operation is likely to be calls to
pmFetch, specifying a list of PMIDs (for example, as constructed by pmLookupName) through pmidlist and numpmid. The call to pmFetch is executed in the context of a source of metrics, instance profile, and collection time, previously established by calls to the functions described in Section 3.8.4, “PMAPI Context Services”.
The principal result from
pmFetch is returned as a tree structured result, described in the Section 3.5, “Performance Metrics Values”.
If one value (for example, associated with a particular instance) for a requested metric is unavailable at the requested time, then there is no associated
pmValue structure in the result. If there are no available values for a metric, then numval is zero and the associated pmValue[] instance is empty; valfmt is undefined in these circumstances, but pmid is correctly set to the PMID of the metric with no values.
If the source of the performance metrics is able to provide a reason why no values are available for a particular metric, this reason is encoded as a standard error code in the corresponding numval; see the
pmerr(1) and pmErrStr(3) man pages. Since all error codes are negative, values for a requested metric are unavailable if numval is less than or equal to zero.
The argument definition and the result specifications have been constructed to ensure that for each PMID in the requested pmidlist there is exactly one
pmValueSet in the result, and that the PMIDs appear in exactly the same sequence in both pmidlist and result. This makes the number and order of entries in result completely deterministic, and greatly simplifies the application programming logic after the call to pmFetch.
The result structure returned by
pmFetch is dynamically allocated using one or more calls to malloc and specialized allocation strategies, and should be released when no longer required by calling pmFreeResult. Under no circumstances should free be called directly to release this space.
As common error conditions are encoded in the result data structure, only serious events (such as loss of connection to PMCD,
malloc failure, and so on) would cause an error value to be returned by pmFetch. Otherwise, the value returned by the pmFetch function is zero.
In Example 3.15, “PMAPI Metrics Services”, the code fragment dumps the values (assumed to be stored in the lval element of the
pmValue structure) of selected performance metrics once every 10 seconds:
Example 3.15. PMAPI Metrics Services
int i, j, sts;
pmID pmidlist[10];
pmResult *result;
time_t now;
/* set up PMAPI context, numpmid and pmidlist[] ... */
while ((sts = pmFetch(10, pmidlist, &result)) >= 0) {
now = (time_t)result->timestamp.tv_sec;
printf("\n@ %s", ctime(&now));
for (i = 0; i < result->numpmid; i++) {
printf("PMID: %s", pmIDStr(result->vset[i]->pmid));
for (j = 0; j < result->vset[i]->numval; j++) {
printf(" 0x%x", result->vset[i]->vlist[j].value.lval);
putchar('\n');
}
}
pmFreeResult(result);
sleep(10);
}Note
If a response is not received back from PMCD within 10 seconds, the
pmFetch times out and returns PM_ERR_TIMEOUT. This is most likely to occur when the PMAPI client and PMCD are communicating over a slow network connection, but may also occur when one of the hosts is extremely busy. The time out period may be modified using the PMCD_REQUEST_TIMEOUT environment variable; see the PCPIntro(1) man page.
The python bindings fetch a pmResult corresponding to a pmid list, which is returned from
pmLookupName. The returned pmresult is passed to pmExtractValue.