PMSEARCH(1)

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

SYNOPSIS
pmsearch [-CdinqsStTV?] [-c config] [-D debug] [-h host] [-p port] [-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 makes use of capabilities of the Performance Co-Pilot (PCP) pmproxy(1) service, the Valkey distributed key-value store and associated ValkeySearch module.

Note that in order to use these services, it is mandatory that pmproxy is communicating with a Valkey key-value server that has the valkey-search.so module loaded. When configured to do so, pmproxy will then automatically index PCP metric names, instance names, metric and instance domain help text into the ValkeySearch store, from PCP archives that it discovers locally. Refer to pmlogger(1) and pmlogger_daily(1) for further details.

By default pmsearch communicates with a local key-value server however the -h and -p options can be used to specify an alternate Valket instance. If this instance is a node of a Valkey cluster, all other instances in the cluster will be discovered and used automatically.

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. Documents are identified using a unique SHA-1 hash which is always displayed in a 40-hexdigit human readable form.

-h host, --host=host
    Connect to the key-value server at host, rather than the one the localhost.

-i, --info
    Report search engine internal metrics.

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

-p port, --port=port
    Connect to the key-value server at port, rather than the default 6379.

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

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

SEE ALSO
PCPIntro(1), pmproxy(1), pmlogger(1) and pmlogger_daily(1).