NAME

       pmTrimNameSpace - prune a performance metrics name space

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmTrimNameSpace(void);

       cc ... -lpcp

DESCRIPTION

       In  some  (rare)  cases  it  is  helpful  to prune the Performance Metrics Name Space (PMNS) to match the
       available metrics.

       The default PMNS that is accessible to a Performance Metrics Application  Programming  Interface  (PMAPI)
       client is provided by the current PMAPI context:

       •  for a PMAPI context of type PM_CONTEXT_HOST the PMNS is provided by pmcd(1) on the associated host and
          no pruning is required

       •  for  a  PMAPI  context of type PM_CONTEXT_ARCHIVE the PMNS is stored within the associated Performance
          Co-Pilot (PCP) archive and no pruning is required

       •  for a PMAPI context of type PM_CONTEXT_LOCAL at the first PMAPI call requiring access to the  PMNS  it
          is  loaded from the default local location $PCP_VAR_DIR/pmns/root (or $PMNS_DEFAULT) and no pruning is
          required.

       If the default PMNS is in effect then calling pmTrimNameSpace is a no-op and returns zero with no  change
       to the PMNS.

       PMAPI  clients  also  have the option of over-riding the default PMNS by loading a local PMNS from a file
       (see PMNS(5) for the format) by calling pmLoadASCIINameSpace(3) or pmLoadNameSpace(3) and  this  is  when
       some PMNS pruning may be useful.

       If  a local PMNS is in effect when pmTrimNameSpace is called then the first action is to restore the PMNS
       to the state as of the completion of the last pmLoadASCIINameSpace(3) or pmLoadNameSpace(3), so that  the
       effects of consecutive calls to pmTrimNameSpace are not additive.

       The subsequent actions of pmTrimNameSpace depend on the type of the current PMAPI context.

       •  For  a  context  of  type PM_CONTEXT_ARCHIVE the local PMNS is trimmed to exclude metrics for which no
          description can be found in the PCP archive.  The PMNS is further trimmed  to  remove  empty  subtrees
          that  do  not  contain  any performance metric.  Since PCP archives usually contain some subset of all
          metrics named in a PMNS, pmTrimNameSpace effectively prunes the application's PMNS to contain only the
          names of the metrics in the archive.

       •  For a context of type PM_CONTEXT_HOST or PM_CONTEXT_LOCAL no further action is required.

       On success, pmTrimNameSpace returns zero.

DIAGNOSTICS

       PM_ERR_NOPMNS
              there has been some earlier problem with establishing the relevant PMNS

       PM_ERR_NOCONTEXT
              the current PMAPI context is invalid

SEE ALSO

       pmlogger(1), PMAPI(3), pmLoadASCIINameSpace(3), pmLoadNameSpace(3), pmNewContext(3) and PMNS(5).

Performance Co-Pilot                                   PCP                                    PMTRIMNAMESPACE(3)