1PMSERIESSETUP(3)           Library Functions Manual           PMSERIESSETUP(3)
2
3
4

NAME

6       pmSeriesQuery,  pmSeriesValues,  pmSeriesLoad  -  fast,  scalable  time
7       series querying
8

C SYNOPSIS

10       #include <pcp/pmwebapi.h>
11
12       int pmSeriesQuery(pmSeriesSettings *sp, sds *query, pmSeriesFlags
13               flags, void *arg);
14       int pmSeriesValues(pmSeriesSettings *sp, pmSeriesTimeWindow *window,
15               int count, sds *series, void *arg);
16
17       int pmSeriesLoad(pmSeriesSettings *sp, sds *query, pmSeriesFlags flags,
18               void *arg);
19
20       cc ... -lpcp_web
21

DESCRIPTION

23       Searching  for time series identifiers and values using the Performance
24       Co-Pilot (PCP) fast, scalable time series services  is  achieved  using
25       the pmseries(1) utility, and associated pmproxy(1) REST API service.
26
27       The implementation of these facilities is shared and available for oth‐
28       er programs to use as well.   The  functionality  is  provided  through
29       asynchronous  APIs,  which  function  in  an event-driven fashion where
30       callbacks are invoked for each set  of  series  identifiers  or  values
31       structure being returned.  These callbacks must be registered using pm‐
32       SeriesSetup(3) before any query API calls are made.
33
34       As a general pattern, these interfaces take an opaque (void *  pointer)
35       parameter,  arg.   This pointer will be passed through unchanged and is
36       typically used to access a data structure maintaining state within  the
37       calling program.
38
39       Depending on the pmseries query string provided, pmSeriesQuery operates
40       in one of two modes.
41
42       Firstly, if no time window specification is provided (square brackets),
43       then  the interface will return only matching series identifiers and no
44       values.  These identifiers are returned via the on_match callback  reg‐
45       istered using pmSeriesSetup.
46
47       The  second  mode  is  where a time window specification is used in the
48       query string, or when the pmSeriesValues interface is used.  This  mode
49       provides  values  and  time stamps for all matching time series identi‐
50       fiers having data points within the  provided  time  window.   In  this
51       case, the results are returned via the on_value callback registered us‐
52       ing pmSeriesSetup.
53
54       Further metadata (metric names, labels, units,  semantics,  type,  etc)
55       about  matched  time  series and their values can be obtained using the
56       interfaces described on the pmSeriesDescs(3) manual page.
57
58       Typically, loading of time series is handled automatically by  the  pm‐
59       proxy daemon, which uses the pmDiscoverSetup(3) series of interfaces to
60       automatically detect and load  logged  time  series  from  pmlogger(1).
61       However,  it  is  also possible to manually load time series from a PCP
62       archive using the pmSeriesLoad interface.  The  provided  query  string
63       must  provide  an  archive  or  directory  to  load data from using the
64       source.path keyword.
65

DIAGNOSTICS

67       Where these functions return a status code, this is always zero on suc‐
68       cess.  On failure a negative PMAPI error code is returned.
69

SEE ALSO

71       pmproxy(1),  pmlogger(1), pmSeriesSetup(3), pmSeriesDescs(3), pmDiscov‐
72       erSetup(3), PMAPI(3) and PMWEBAPI(3).
73
74
75
76Performance Co-Pilot                  PCP                     PMSERIESSETUP(3)
Impressum