pmsearch1

Usage

Overview

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).

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.