# pmseriesdescs

## 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 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 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  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 val‐
           ue 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.
    


* * *