NAME

       pmSearchSetup,          pmSearchSetSlots,         pmSearchSetEventLoop,         pmSearchSetConfiguration,
       pmSearchSetMetricRegistry, pmSearchClose - fast, scalable and fulltext capable search services

C SYNOPSIS

       #include <pcp/pmwebapi.h>

       int pmSearchSetup(pmSearchModule *module, void *arg);

       int pmSearchSetSlots(pmSearchModule *module, void *slots);
       int pmSearchSetEventLoop(pmSearchModule *module, void *events);
       int pmSearchSetConfiguration(pmSearchModule *module, struct dict *config);
       int pmSearchSetMetricRegistry(pmSearchModule *module, struct mmv_registry *registry);

       int pmSearchClose(pmSearchModule *module);

       cc ... -lpcp_web

DESCRIPTION

       The pmSearchSetup and related API functions prepare an application for accessing the  fast  and  scalable
       metric, instance and instance domain, fulltext capable, searching functionality of the Performance Co-Pi‐
       lot (PCP).

       This  functionality is provided trough asynchronous APIs, which function in event-driven fashion. The in‐
       terface described here prepare a given search module which  associates  callback  routines  with  certain
       asynchronous events that occur as part of servicing search 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) arg parameter.  This pointer  will  be  passed  through  un‐
       changed and is typically used to access a data structure maintaining state within the calling program.

       Where  asynchronous  setup  is required by pmSearchSetup its completion will be indicated throught use of
       the on_setup callback, which is part of the passed in pmSearchModule structure. This structure also  pro‐
       vides  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 pmSearchSetup to handle events are as follows:

       pmSearchTextResultCallBack on_text_result
            Callback is called once for each item of search result that matches a  given  query  passed  by  pm‐
            SearchTextInDom(3), pmSearchTextQuery(3), pmSearchTextSuggest(3).

       pmSearchMetricsCallBack on_metrics
            Callback is called for results of a call to pmSearchInfo(3).

       pmSearchDoneCallBack 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  pmSearchSetSlots  (redis), pmSearchSetEventLoop (libuv), pmSearchSetConfiguration
       (configuration file) and pmSearchSetMetricRegistry (MMV instrumentation) interfaces provide  a  mechanism
       for passing in state for each of the associated subsystems.

       Finally, a call to pmSearchClose is used to end services available from a search module previously ensta‐
       blished through pmSearchSetup.

       Within  PCP,  the pmproxy(1) and pmsearch(1) utilities are the primary users of the interfaces, providing
       REST API and command line search 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), pmsearch(1), redis-server(1), mmv_stats_registry(3), pmSearchInfo(3), pmSearch‐
       TextInDom(3), pmSearchTextQuery(3), pmSearchTextSuggest(3), PMAPI(3) and PMWEBAPI(3).

Performance Co-Pilot                                   PCP                                      PMSEARCHSETUP(3)