pmseriesdescs(3) — Linux manual page


PMSERIESSETUP(3)          Library Functions Manual          PMSERIESSETUP(3)

NAME         top

       pmSeriesDescs,   pmSeriesLabels,   pmSeriesLabelValues,   pmSeriesIn‐
       stances,  pmSeriesMetrics,  pmSeriesSources  -  fast,  scalable  time
       series metadata

C SYNOPSIS         top

       #include <pcp/pmwebapi.h>

       int pmSeriesDescs(pmSeriesSettings *sp, int count, sds *series, void
       int pmSeriesLabels(pmSeriesSettings *sp, int count, sds *series, void
       int pmSeriesLabelValues(pmSeriesSettings *sp, int count, sds *labels,
               void *arg);
       int pmSeriesInstances(pmSeriesSettings *sp, int count, sds *series,
               void *arg);
       int pmSeriesMetrics(pmSeriesSettings *sp, int count, sds *series,
               void *arg);
       int pmSeriesSources(pmSeriesSettings *sp, int count, sds *series,
               void *arg);

       cc ... -lpcp_web

DESCRIPTION         top

       Each performance metric and data source forming part of the
       Performance Co-Pilot (PCP) fast, scalable time series service has
       certain properties (metadata) associated with it.  These properties
       can be queried using the interfaces described here.

       This functionality is provided through asynchronous APIs, which
       function in an event-driven fashion where callbacks are invoked for
       each metadata structure being returned.

       As a general pattern, all interfaces in these APIs that need to
       invoke callbacks provided by the calling program (see
       pmSeriesSetup(3)) will take an opaque (void * pointer) parameter,
       arg.  This pointer will be passed through unchanged and is typically
       used to access a data structure maintaining state within the calling

       With a couple of exceptions, these interfaces tend to operate in one
       of two modes.  Firstly, one invocation is available to query metadata
       for a specific (non-zero) count of time series.  A second, (zero)
       count, mode returns all available metadata of that type, across all
       time series.

       In order to retrieve metric descriptor information for one or more
       time series, the pmSeriesDescs interface is used.  For each valid
       series identifier provided, a callback will be invoked providing the
       metric units, semantics, and type as well as other identifiers
       associated with it (pmID, InDom and source identifier).  When this
       call is issued with a zero value for count, It is an error to pass a
       zero or negative value of count into this interface.

       To extract label names and values, the pmSeriesLabels interface is
       used.  With a non-zero value for count valid series identifiers, this
       routine will invoke a callback once for each label name and once for
       each label name:value pair, for labels associated with those time
       series.  If called with a count of zero, this interface will return
       (via the label name callback) all label names that have observed to
       date - not associated with specific time series.  The
       pmSeriesLabelValues interface is comparable to this latter mode,
       except will return all label values that have been observed to date
       for the given array of labels names (not associated with any specific
       time series identifiers).

       pmSeriesInstances can be used to find metadata about instance domains
       and instance identifiers associated with a given (non-zero) count of
       time series identifiers.  If a zero value is passed for count then
       all instance names observed to date will be returned.

       pmSeriesMetrics can be used to find metric names associated with a
       given (non-zero) count of time series identifiers.  If a zero value
       is passed for count then all metric names observed to date will be

       pmSeriesSources can be used to find metadata about the source of
       metrics - that is, host names and archive file paths.  If a zero
       value is passed for count then all metric sources observed to date
       will be returned.

DIAGNOSTICS         top

       Where these functions return a status code, this is always zero on
       success.  On failure a negative PMAPI error code is returned.

SEE ALSO         top

       pmproxy(1), pmlogger(1), pmseries(1), pmSeriesQuery(3),
       pmSeriesSetup(3), PMAPI(3) and PMWEBAPI(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨⟩ on
       2020-06-09.  (At that time, the date of the most recent commit that
       was found in the repository was 2020-06-09.)  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

Performance Co-Pilot                 PCP                    PMSERIESSETUP(3)