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 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 page.
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
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).