NAME

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

C SYNOPSIS

       #include <pcp/pmwebapi.h>

       int pmSeriesQuery(pmSeriesSettings *sp, sds *query, pmSeriesFlags flags, void *arg);
       int pmSeriesWindow(pmSeriesSettings *sp, sds *window, pmSeriesTimeWindow *window, 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.   A  helper routine to create a time window structure from a square-bracket
       enclosed time specification is provided in the form of pmSeriesWindow.

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