NAME¶

pmSearchSetup, pmSearchSetSlots, pmSearchSetEventLoop, pmSearchSetConfiguration, pmSearchSetMetricRegistry, pmSearchClose - fast, scalable and full-text 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 full-text search functionality of the Performance Co-Pilot (PCP).

The search engine uses a local SQLite FTS5 full-text index. A build-time base index at $PCP_SHARE_DIR/lib/pmsearch.index provides help text for all metrics shipped with PCP. Each night, pmsearch_daily(1) copies the base index to $PCP_VAR_DIR/lib/pmsearch.index and extends it with instance names from the running system. When the nightly index exists it is used; otherwise the base index is used as a fallback.

The interfaces described here prepare a given search module which associates callback routines with 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 unchanged and is typically used to access a data structure maintaining state within the calling program.

On completion of pmSearchSetup the on_setup callback will be invoked. This callback is part of the passed in pmSearchModule structure, which also provides for custom diagnostics handling through the on_info callback. 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 pmSearchTextInDom(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 and pmSearchSetEventLoop are retained for API compatibility but have no effect. pmSearchSetConfiguration (configuration file) and pmSearchSetMetricRegistry (MMV instrumentation) 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 established 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.

FILES¶

$PCP_VAR_DIR/lib/pmsearch.index

Nightly search index (SQLite FTS5 database), a copy of the base index extended with runtime instance data by pmsearch_daily(1).

$PCP_SHARE_DIR/lib/pmsearch.index

Build-time base index shipped with the PCP package.

SEE ALSO¶

pmsearch(1), pmsearch_daily(1), pmproxy(1), pmlogger(1), mmv_stats_registry(3), pmSearchInfo(3), pmSearchTextInDom(3), pmSearchTextQuery(3), pmSearchTextSuggest(3), PMAPI(3) and PMWEBAPI(3).