1PMTRIMNAMESPACE(3)         Library Functions Manual         PMTRIMNAMESPACE(3)
2
3
4

NAME

6       pmTrimNameSpace - prune a performance metrics name space
7

C SYNOPSIS

9       #include <pcp/pmapi.h>
10
11       int pmTrimNameSpace(void);
12
13       cc ... -lpcp
14

DESCRIPTION

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 lo‐
32          cation  $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

DIAGNOSTICS

65       PM_ERR_NOPMNS
66              there  has been some earlier problem with establishing the rele‐
67              vant PMNS
68
69       PM_ERR_NOCONTEXT
70              the current PMAPI context is invalid
71

SEE ALSO

73       pmlogger(1), PMAPI(3), pmLoadASCIINameSpace(3), pmLoadNameSpace(3), pm‐
74       NewContext(3) and PMNS(5).
75
76
77
78Performance Co-Pilot                  PCP                   PMTRIMNAMESPACE(3)
Impressum