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