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 call‐
       backs 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 pmSeries‐
       Values interface is used.  This mode provides values and time stamps for all matching time series identi‐
       fiers 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 pmDisco‐
       verSetup(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  in‐
       terface.   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 PMWE‐
       BAPI(3).

Performance Co-Pilot                                   PCP                                      PMSERIESQUERY(3)