pmtrimnamespace(3) — Linux manual page

PMTRIMNAMESPACE(3)      Library Functions Manual      PMTRIMNAMESPACE(3)

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).

COLOPHON

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨http://www.pcp.io/⟩.  If you have a bug report for this manual
       page, send it to pcp@groups.io.  This page was obtained from the
       project's upstream Git repository
       ⟨https://github.com/performancecopilot/pcp.git⟩ on 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Performance Co-Pilot               PCP                PMTRIMNAMESPACE(3)

Pages that refer to this page: pmfetcharchive(3), pmgetpmnslocation(3), pmloadasciinamespace(3), pmloadnamespace(3)

---