pmLookupName - translate performance metric names into PMIDs
#include <pcp/pmapi.h>
int pmLookupName(int numpmid, const char **namelist, pmID *pmidlist);
cc ... -lpcp
Given a list in
namelist containing
numpmid full pathnames for
performance metrics from a Performance Metrics Name Space (PMNS),
pmLookupName returns the list of associated Performance Metric
Identifiers (PMIDs) via
pmidlist.
The result from
pmLookupName depends on the presence of any lookup
failures, their severity and the number of metrics being looked up.
- 1.
- If there are no lookup failures, the return value will be
numpmid.
- 2.
- If a fatal error is encountered, the return value will be
less than 0. For example PM_ERR_TOOSMALL, PM_ERR_NOPMNS or
PM_ERR_IPC.
- 3.
- If numpmid is greater than one and non-fatal
error(s) are encountered, the return value is the number of metric names
that have successfully been looked up (greater than or equal to zero and
less than or equal to numpmid).
- 4.
- If numpmid is one and a non-fatal error is
encountered, the return value is the error code (less than zero).
When errors are encountered, any metrics that cannot be looked up result in the
corresponding element of
pmidlist being set to
PM_ID_NULL.
The slightly convoluted error protocol allows bulk lookups, then probing for
more error details in the case of a specific failure, as shown in the
EXAMPLES section below.
Note that the error protocol guarantees there is a 1:1 relationship between the
elements of
namelist and
pmidlist, hence both lists contain
exactly
numpmid elements. For this reason, the caller is expected to
have pre-allocated a suitably sized array for
pmidlist.
#include <pcp/pmapi.h>
#define NUMPMID (sizeof(names)/sizeof(const char *))
const char *names[] = {
"sample.bin",
"sample",
"sample.bog",
"sample.secret.bar",
"sample.secret.bar.bad"
};
pmID pmids[NUMPMID];
int
main(int argc, char **argv)
{
int sts;
int numpmid = NUMPMID;
pmNewContext(PM_CONTEXT_HOST, "local:");
sts = pmLookupName(numpmid, names, pmids);
if (sts < 0) {
fprintf(stderr, "pmLookupName failed: %s0, pmErrStr(sts));
exit(1);
}
if (sts != numpmid) {
/*
* some of the lookups failed ... report the reason(s)
*/
int i;
for (i = 0; i < numpmid; i++) {
if (pmids[i] != PM_ID_NULL) continue;
/* this one failed */
sts = pmLookupName(1, &names[i], &pmids[i]);
fprintf(stderr, "%s: lookup failed: %s0, names[i], pmErrStr(sts));
}
exit(1);
}
/* all good ... */
...
}
- PM_ERR_TOOSMALL
-
numpmid must be at least 1
- PM_ERR_NOPMNS
- Failed to access a PMNS for operation. Note that if the
application hasn't a priori called pmLoadNameSpace(3) and wants to
use the distributed PMNS, then a call to pmLookupName must be made
after the creation of a context (see pmNewContext(3)).
- PM_ERR_NAME
-
namelist[0] does not correspond to a valid metric
name in the PMNS.
- PM_ERR_NONLEAF
-
namelist[0] refers to a node in the PMNS but it was
not a leaf node.
- PM_ERR_*
- Other diagnostics are for protocol failures when accessing
the distributed PMNS.
PMAPI(3),
pmGetChildren(3),
pmGetChildrenStatus(3),
pmGetConfig(3),
pmLoadNameSpace(3),
pmNameID(3),
pmNewContext(3),
pcp.conf(5) and
pcp.env(5).