|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | C SYNOPSIS | DESCRIPTION | DIAGNOSTICS | SEE ALSO | COLOPHON |
|
|
|
PMSERIESQUERY(3) Library Functions Manual PMSERIESQUERY(3)
pmSeriesQuery, pmSeriesWindow, pmSeriesValues, pmSeriesLoad -
fast, scalable time series querying
#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
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.
Where these functions return a status code, this is always zero on
success. On failure a negative PMAPI error code is returned.
pmproxy(1), pmlogger(1), pmSeriesSetup(3), pmSeriesDescs(3),
pmDiscoverSetup(3), PMAPI(3) and PMWEBAPI(3).
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-08-11. (At that time, the date of the most recent commit
that was found in the repository was 2025-08-11.) 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)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|