pmseriesquery(3) — Linux manual page

PMSERIESQUERY(3)        Library Functions Manual        PMSERIESQUERY(3)

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 Per‐
       formance 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 iden‐
       tifiers 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 un‐
       changed and is typically used to access a  data  structure  main‐
       taining 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  ex‐
       pression.   The  query  expression  may  be  retrieved  with  the
       pmSeriesExprs(3) API call.  See also PMWEBAPI(3) and the  -e  op‐
       tion 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 in‐
       terfaces 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).

COLOPHON

       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   2024-06-14.
       (At  that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  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)

---