NAME

       pmSeriesSetup,     pmSeriesSetSlots,    pmSeriesSetEventLoop,    pmSeriesSetConfiguration,
       pmSeriesSetMetricRegistry, pmSeriesClose - fast, scalable time series services

C SYNOPSIS

       #include <pcp/pmwebapi.h>

       int pmSeriesSetup(pmSeriesModule *module, pmSeriesCallBacks *callbacks, void *arg);

       int pmSeriesSetSlots(pmSeriesModule *module, void *slots);
       int pmSeriesSetEventLoop(pmSeriesModule *module, void *uvloop);
       int pmSeriesSetConfiguration(pmSeriesModule *module, struct dict *config);
       int pmSeriesSetMetricRegistry(pmSeriesModule *module, struct mmv_registry *registry);

       int pmSeriesClose(pmSeriesModule *module);

       cc ... -lpcp_web

DESCRIPTION

       The pmSeriesSetup and related API functions prepare an application for accessing the fast,
       scalable time series querying functionality of the Performance Co-Pilot (PCP).

       This  functionality  is  provided  through  asynchronous APIs, which function in an event-
       driven fashion.  The interfaces described here prepare a given time  series  module  which
       associates  callback  routines  with  certain  asynchronous  events  that occur as part of
       servicing time series requests.

       As a general pattern, all interfaces in these APIs that need to invoke callbacks  provided
       by  the calling program will 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.

       Where  asynchronous  setup  is  required by pmSeriesSetup its completion will be indicated
       through use of the on_setup callback, which  is  part  of  the  passed  in  pmSeriesModule
       structure.   This  structure  also  provides  for custom diagnostics handling, through the
       on_info callback.  These are self-explanatory,  see  <pcp/pmwebapi.h>  for  exact  calling
       conventions.

       The callbacks registered by pmSeriesSetup to handle events are as follows:

       pmSeriesMatchCallBack on_match
            When  a time series query discovers time series identifiers that match the query, the
            on_match callback will be called once for every series identifier (SID).  The SID  is
            a unique 40-byte ASCII representation of a SHA hash.

       pmSeriesDescCallBack on_desc
            Metric  descriptor  requests from pmSeriesDescs(1) will invoke this callback once for
            each series identifier.

       pmSeriesInstCallBack on_inst
            Instance identification callback - internal (numeric) and external (string)  instance
            identifiers,  as well as time series and source (host) SHA1 identifiers.  Called once
            for each instance.   The  associated  series  identifier  is  also  provided  to  the
            callback.

       pmSeriesLabelCallBack on_labelmap
            Provides metric labels (name and value mappings) for each series identifier passed to
            pmSeriesLabels(1).

       pmSeriesStringCallBack on_instance
            Provides an instance name for a call to pmSeriesInstances(1)- the callback is  called
            once  for  each  instance name.  The associated series identifier is also provided to
            the callback.

       pmSeriesStringCallBack on_context
            Provides a context name for a call to pmSeriesSources(1)- the callback is called once
            for  each  source  (hostname  or  archive).  The associated source identifier is also
            provided to the callback.

       pmSeriesStringCallBack on_metric
            Provides a metric name for a call to pmSeriesMetrics(1)- the callback is called  once
            for  each  metric  name.   The  associated  series identifier is also provided to the
            callback.

       pmSeriesStringCallBack on_label
            Provides a label name for a call to pmSeriesLabels(1)- the callback  is  called  once
            for  each  label  name.   The  associated  series  identifier is also provided to the
            callback.

       pmSeriesValueCallBack on_value
            Calls to the pmSeriesQuery interface that provide a time window may result in  values
            being found for matching time series.  The on_value callback will be invoked once for
            each time series value, also providing the  sample  timestamp  (in  both  string  and
            binary  form,  as  a  time  in  nanoseconds  since the epoch).  The associated series
            identifier is also provided to the callback.

       pmSeriesDoneCallBack on_done
            On completion of all asynchronous interfaces that return success (zero return  code),
            this  callback  will be called.  It provides a status code indicating overall success
            (zero) or failure (negative PMAPI code) of the operation.

       The   helper   functions   pmSeriesSetSlots   (redis),    pmSeriesSetEventLoop    (libuv),
       pmSeriesSetConfiguration   (configuration   file)   and   pmSeriesSetMetricRegistry   (MMV
       instrumentation) interfaces provide a mechanism for passing  in  state  for  each  of  the
       associated subsystems.

       Finally,  a  call  to pmSeriesClose is used to end services available from a series module
       previously established through pmSeriesSetup.

       Within PCP, the pmproxy(1) and pmseries(1)  utilities  are  the  primary  users  of  these
       interfaces, providing REST API and command line time series query services respectively.

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),    pmseries(1),    redis-server(1),     mmv_stats_registry(3),
       pmSeriesDescs(3), pmSeriesQuery(3), PMAPI(3) and PMWEBAPI(3).