pmseriesdescs(3) — Linux manual page


PMSERIESDESCS(3)        Library Functions Manual        PMSERIESDESCS(3)

NAME         top

       pmSeriesDescs, pmSeriesLabels, pmSeriesLabelValues,
       pmSeriesInstances, pmSeriesMetrics, pmSeriesSources - fast,
       scalable time series metadata

C SYNOPSIS         top

       #include <pcp/pmwebapi.h>

       int pmSeriesDescs(pmSeriesSettings *sp, int count, sds *series,
               void *arg);
       int pmSeriesLabels(pmSeriesSettings *sp, int count, sds *series,
               void *arg);
       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 Per‐
       formance Co-Pilot (PCP) fast, scalable time  series  service  has
       certain  properties (metadata) associated with it.  These proper‐
       ties 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  typi‐
       cally  used  to  access a data structure maintaining state within
       the calling program.

       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  sec‐
       ond,  (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 pro‐
       viding the metric units, semantics, and type  as  well  as  other
       identifiers  associated with it (pmID, InDom and source identifi‐
       er).  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  in‐

       To  extract  label names and values, the pmSeriesLabels interface
       is used.  With a non-zero value for count  valid  series  identi‐
       fiers,  this  routine  will invoke a callback once for each label
       name and once for each label name:value pair, for labels  associ‐
       ated  with  those  time  series.  If called with a count of zero,
       this interface will return (via the label name callback) all  la‐
       bel  names  that have observed to date - not associated with spe‐
       cific time series.  The pmSeriesLabelValues interface is compara‐
       ble 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 do‐
       mains 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 returned.

       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.  In‐
       formation 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  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

Performance Co-Pilot               PCP                  PMSERIESDESCS(3)

Pages that refer to this page: pmseriesquery(3)pmseriessetup(3)pmwebapi(3)