pmsearch(1)

NAME

pmsearch - help text and names search for metrics, instances and instance domains

SYNOPSIS

pmsearch [-CdinqsStTV?] [-c config] [-D debug] [-N number] [-O offset] [query | indom]

DESCRIPTION

pmsearch performs full text search queries to find metrics using names and help text from metrics, instance domains and instances.

It uses a local SQLite FTS5 full-text search index. A base index is built at package install time containing help text for all PCP metrics from the source tree. Each night, pmsearch_daily(1) copies the base index and extends it with instance names (disk devices, network interfaces, etc.) from the running system.

No external services (such as Redis or Valkey) are required.

OPTIONS

-c config, --config=config: Specify the config file to use.

-C, --no-colour: No highlighting in results text.

-d, --docid: Report document ID of each search result.

-i, --info: Report search index metrics (document count).

-n, --indom: Perform an instance domain related entities search.

-N N, --number=N: Return N, search results at most.

-O N, --offset=N: Paginated results from given offset.

-q, --query: Perform a general text search (default).

-s, --suggest: Perform a name suggestion search.

-S, --score: Report score (rank) of each result.

-T, --total: Report total number of search results.

-t, --times: Report elapsed search execution time.

-V, --version: Display version number and exit.

-?, --help: Display usage message and exit.

EXAMPLES

$ pmsearch kernel idle
Type: metric
Name: kernel.all.cpu.idle
One line: total idle CPU time from /proc/stat for all CPUs
Type: metric
Name: kernel.all.idletime
One line: time the current kernel has been idle since boot
Type: metric
Name: kernel.percpu.cpu.idle
InDom: 60.0
One line: percpu idle CPU time metric from /proc/stat

FILES

$PCP_VAR_DIR/lib/pmsearch.index: Nightly search index (SQLite FTS5 database), rebuilt by pmsearch_daily(1). This is a copy of the base index extended with runtime instance data.

$PCP_SHARE_DIR/lib/pmsearch.index: Build-time base index containing all metrics from the PCP source tree. Used as a fallback when the nightly index is not yet available.

PCP ENVIRONMENT

Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the file /etc/pcp.conf contains the local values for these variables. The $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

For environment variables affecting PCP tools, see pmGetOptions(3).

DEBUGGING OPTIONS

The -D or --debug option enables the output of additional diagnostics on stderr to help triage problems, although the information is sometimes cryptic and primarily intended to provide guidance for developers rather than for end-users. debug is a comma separated list of debugging options; use pmdbg(1) with the -l option to obtain a list of the available debugging options and their meaning.