---
name: "pmsearch"
section: "1"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pmsearch"
---

# pmsearch(1)

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

## 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)](/pmsearch_daily/1.md) 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)](/pmsearch_daily/1.md). 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)](/pcp.conf/5.md).

For environment variables affecting PCP tools, see [**pmGetOptions**(3)](/pmGetOptions/3.md).

## 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)](/pmdbg/1.md) with the **-l** option to obtain a list of the available debugging options and their meaning.

## SEE ALSO

[**PCPIntro**(1)](/PCPIntro/1.md), [**pmsearch\_daily**(1)](/pmsearch_daily/1.md), [**pmproxy**(1)](/pmproxy/1.md), [**pmlogger**(1)](/pmlogger/1.md) and [**pmlogger\_daily**(1)](/pmlogger_daily/1.md).