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 invoca‐
       tion 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 inter‐
       face 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  iden‐
       tifier).  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 re‐
       turned.

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

Performance Co-Pilot                                   PCP                                      PMSERIESDESCS(3)