1PMTRIMNAMESPACE(3) Library Functions Manual PMTRIMNAMESPACE(3)
2
3
4
6 pmTrimNameSpace - prune a performance metrics name space
7
9 #include <pcp/pmapi.h>
10
11 int pmTrimNameSpace(void);
12
13 cc ... -lpcp
14
16 In some (rare) cases it is helpful to prune the Performance Metrics
17 Name Space (PMNS) to match the available metrics.
18
19 The default PMNS that is accessible to a Performance Metrics Applica‐
20 tion Programming Interface (PMAPI) client is provided by the current
21 PMAPI context:
22
23 · for a PMAPI context of type PM_CONTEXT_HOST the PMNS is provided by
24 pmcd(1) on the associated host and no pruning is required
25
26 · for a PMAPI context of type PM_CONTEXT_ARCHIVE the PMNS is stored
27 within the associated Performance Co-Pilot (PCP) archive log and no
28 pruning is required
29
30 · for a PMAPI context of type PM_CONTEXT_LOCAL at the first PMAPI call
31 requiring access to the PMNS it is loaded from the default local
32 location $PCP_VAR_DIR/pmns/root (or $PMNS_DEFAULT) and no pruning is
33 required.
34
35 If the default PMNS is in effect then calling pmTrimNameSpace is a no-
36 op and returns zero with no change to the PMNS.
37
38 PMAPI clients also have the option of over-riding the default PMNS by
39 loading a local PMNS from a file (see PMNS(5) for the format) by call‐
40 ing pmLoadASCIINameSpace(3) or pmLoadNameSpace(3) and this is when some
41 PMNS pruning may be useful.
42
43 If a local PMNS is in effect when pmTrimNameSpace is called then the
44 first action is to restore the PMNS to the state as of the completion
45 of the last pmLoadASCIINameSpace(3) or pmLoadNameSpace(3), so that the
46 effects of consecutive calls to pmTrimNameSpace are not additive.
47
48 The subsequent actions of pmTrimNameSpace depend on the type of the
49 current PMAPI context.
50
51 · For a context of type PM_CONTEXT_ARCHIVE the local PMNS is trimmed
52 to exclude metrics for which no description can be found in the PCP
53 archive log. The PMNS is further trimmed to remove empty subtrees
54 that do not contain any performance metric. Since PCP archives usu‐
55 ally contain some subset of all metrics named in a PMNS, pmTrim‐
56 NameSpace effectively prunes the application's PMNS to contain only
57 the names of the metrics in the archive.
58
59 · For a context of type PM_CONTEXT_HOST or PM_CONTEXT_LOCAL no further
60 action is required.
61
62 On success, pmTrimNameSpace returns zero.
63
65 pmlogger(1), PMAPI(3), pmLoadASCIINameSpace(3), pmLoadNameSpace(3),
66 pmNewContext(3) and PMNS(5).
67
69 PM_ERR_NOPMNS
70 there has been some earlier problem with establishing the rele‐
71 vant PMNS
72
73 PM_ERR_NOCONTEXT
74 the current PMAPI context is invalid
75
76
77
78Performance Co-Pilot PCP PMTRIMNAMESPACE(3)