pmseriesquery(3) — Linux manual page


PMSERIESQUERY(3)        Library Functions Manual        PMSERIESQUERY(3)

NAME         top

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

C SYNOPSIS         top

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

       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 2023-12-22.
       (At that time, the date of the most recent commit that was found
       in the repository was 2023-12-16.)  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: pmseriesdescs(3)pmseriessetup(3)pmwebapi(3)