|
HTML rendering created 2024-06-26 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 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.
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
[email protected]. 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
[email protected]
Performance Co-Pilot PCP PMSERIESQUERY(3)
Pages that refer to this page: pmseriesdescs(3), pmseriessetup(3), pmwebapi(3)
|
HTML rendering created 2024-06-26 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. |
|