'\"macro stdmacro
.\"
.\" Copyright (c) 2019 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.TH PMSERIESSETUP 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmSeriesQuery\f1,
\f3pmSeriesValues\f1,
\f3pmSeriesLoad\f1 \- fast, scalable time series querying
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmwebapi.h>
.sp
.ad l
.hy 0
.in +8n
.ti -8n
int pmSeriesQuery(pmSeriesSettings *\fIsp\fP, sds *\fIquery\fP, pmSeriesFlags \fIflags\fP, void *\fIarg\fP);
.br
.ti -8n
int pmSeriesValues(pmSeriesSettings *\fIsp\fP, pmSeriesTimeWindow *\fIwindow\fP, int \fIcount\fP, sds *\fIseries\fP, void *\fIarg\fP);
.sp
.ti -8n
int pmSeriesLoad(pmSeriesSettings *\fIsp\fP, sds *\fIquery\fP, pmSeriesFlags \fIflags\fP, void *\fIarg\fP);
.sp
.in
.hy
.ad
cc ... \-lpcp_web
.ft 1
.SH DESCRIPTION
Searching for time series identifiers and values using the Performance
Co-Pilot (PCP) fast, scalable time series services is achieved using the
.BR pmseries (1)
utility, and associated
.BR pmproxy (1)
REST API service.
.PP
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
.BR pmSeriesSetup (3)
before any query API calls are made.
.PP
As a general pattern, these interfaces take an opaque (void * pointer)
parameter,
.IR arg .
This pointer will be passed through unchanged and is typically
used to access a data structure maintaining state within the calling
program.
.PP
Depending on the
.B pmseries
.I query
string provided,
.BR pmSeriesQuery
operates in one of two modes.
.PP
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
.I on_match
callback registered using
.BR pmSeriesSetup .
.PP
The second mode is where a time window specification is used in the
.I query
string, or when the
.B pmSeriesValues
interface is used.
This mode provides values and time stamps for all matching time series
identifiers having data points within the provided time
.IR window .
In this case, the results are returned via the
.I on_value
callback registered using
.BR pmSeriesSetup .
.PP
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
.BR pmSeriesDescs (3)
manual page.
.PP
Typically, loading of time series is handled automatically by the
.B pmproxy
daemon, which uses the
.BR pmDiscoverSetup (3)
series of interfaces to automatically detect and load logged time series
from
.BR pmlogger (1).
However, it is also possible to manually load time series from a PCP
archive using the
.B pmSeriesLoad
interface.
The provided
.I query
string must provide an archive or directory to load data from using the
.I source.path
keyword.
.SH DIAGNOSTICS
Where these functions return a status code, this is always zero on success.
On failure a negative PMAPI error code is returned.
.SH SEE ALSO
.BR pmproxy (1),
.BR pmlogger (1),
.BR pmSeriesSetup (3),
.BR pmSeriesDescs (3),
.BR pmDiscoverSetup (3),
.BR PMAPI (3)
and
.BR PMWEBAPI (3).