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