pmseriesquery(3) — Linux manual page

NAME | C SYNOPSIS | DESCRIPTION | DIAGNOSTICS | SEE ALSO | COLOPHON

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 Perfor‐
       mance  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 fash‐
       ion where callbacks are invoked for each set of series identifiers
       or values structure being returned.  These callbacks must be  reg‐
       istered  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 un‐
       changed and is typically used to access a data structure maintain‐
       ing state within the calling program.

       Depending on the pmseries query string provided, pmSeriesQuery op‐
       erates 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 dynami‐
       cally  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 cre‐
       ate 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 inter‐
       faces  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.  In‐
       formation about the project can be found at  ⟨http://www.pcp.io/⟩.
       If  you  have  a  bug  report  for  this  manual  page, send it to
       pcp@groups.io.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩  on
       2025-02-02.   (At  that  time,  the date of the most recent commit
       that was found in the repository was 2025-01-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 man-pages@man7.org

Performance Co-Pilot               PCP                   PMSERIESQUERY(3)

Pages that refer to this page: pmseriesdescs(3)pmseriessetup(3)pmwebapi(3)