NAME

       pmSeriesQuery, pmSeriesValues, pmSeriesLoad - fast, scalable time series querying

C SYNOPSIS

       #include <pcp/pmwebapi.h>

       int pmSeriesQuery(pmSeriesSettings *sp, sds *query, pmSeriesFlags flags, void *arg);
       int pmSeriesValues(pmSeriesSettings *sp, pmSeriesTimeWindow *window, int count, sds
               *series, void *arg);

       int pmSeriesLoad(pmSeriesSettings *sp, sds *query, pmSeriesFlags flags, void *arg);

       cc ... -lpcp_web

DESCRIPTION

       Searching for time series identifiers and values  using  the  Performance  Co-Pilot  (PCP)
       fast,  scalable  time  series  services  is  achieved  using  the pmseries(1) utility, and
       associated pmproxy(1) REST API service.

       The implementation of these facilities is shared and available for other programs  to  use
       as  well.   The  functionality is provided through asynchronous APIs, which function in an
       event-driven fashion where callbacks are invoked for each set  of  series  identifiers  or
       values   structure   being   returned.    These   callbacks   must   be  registered  using
       pmSeriesSetup(3) before any query API calls are made.

       As a general pattern, these interfaces 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.

       Depending on the pmseries query string provided, pmSeriesQuery  operates  in  one  of  two
       modes.

       Firstly, if no time window specification is provided (square brackets), then the interface
       will return only matching  series  identifiers  and  no  values.   These  identifiers  are
       returned  via  the  on_match  callback  registered  using  pmSeriesSetup.   If  the  query
       expression includes function calls or arithmetic  operators  (rather  than  simple  metric
       names),  then  the  returned identifier is dynamically created and persistently associated
       with the expression.  The query expression may be retrieved with the pmSeriesExprs(3)  API
       call.  See also PMWEBAPI(3) and the -e option to pmseries(1).

       The  second mode is where a time window specification is used in the query string, or when
       the pmSeriesValues interface is used.  This mode provides values and time stamps  for  all
       matching  time  series identifiers having data points within the provided time window.  In
       this  case,  the  results  are  returned  via  the  on_value  callback  registered   using
       pmSeriesSetup.

       Further  metadata  (metric  names, labels, units, semantics, type, etc) about matched time
       series  and  their  values  can  be  obtained  using  the  interfaces  described  on   the
       pmSeriesDescs(3) manual page.

       Typically,  loading  of  time series is handled automatically by the pmproxy daemon, which
       uses the pmDiscoverSetup(3) series of interfaces to automatically detect and  load  logged
       time  series  from pmlogger(1).  However, it is also possible to manually load time series
       from a PCP archive using the pmSeriesLoad  interface.   The  provided  query  string  must
       provide an archive or directory to load data from using the source.path keyword.

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), pmSeriesSetup(3), pmSeriesDescs(3), pmDiscoverSetup(3),  PMAPI(3)
       and PMWEBAPI(3).