pmSeriesQuery(3) — Linux manual page


PMSERIESQUERY(3)          Library Functions Manual          PMSERIESQUERY(3)

NAME         top

       pmSeriesQuery, pmSeriesValues, pmSeriesLoad - fast, scalable time se‐
       ries querying

C SYNOPSIS         top

       #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         top

       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.

       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         top

       Where these functions return a status code, this is always zero on
       success.  On failure a negative PMAPI error code is returned.

SEE ALSO         top

       pmproxy(1), pmlogger(1), pmSeriesSetup(3), pmSeriesDescs(3),
       pmDiscoverSetup(3), PMAPI(3) and PMWEBAPI(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨⟩ on
       2020-11-01.  (At that time, the date of the most recent commit that
       was found in the repository was 2020-10-30.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

Performance Co-Pilot                 PCP                    PMSERIESQUERY(3)

Pages that refer to this page: pmSeriesClose(3)pmseriesdescs(3)pmSeriesDescs(3)pmSeriesInstances(3)pmSeriesLabels(3)pmSeriesLabelValues(3)pmSeriesMetrics(3)pmSeriesSetConfiguration(3)pmSeriesSetEventLoop(3)pmSeriesSetMetricRegistry(3)pmSeriesSetSlots(3)pmseriessetup(3)pmSeriesSetup(3)pmSeriesSources(3)pmwebapi(3)PMWEBAPI(3)