NAME

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

C SYNOPSIS

       #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

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

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

SEE ALSO

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