PMSEARCH(1)

💅 pmsearch — the manual, but make it make sense

okay bestie, welcome to pmsearch, from the General Commands Manual section (that's the manual name, iykyk). it's a search tool for metrics, instances and instance domains, and honestly? it's giving ✨ find anything ✨. let's go.

---

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

okay so pmsearch does full text search queries to find metrics, using names and help text from metrics, instance domains and instances. literally just type words, get metrics. iconic.

it uses a local SQLite FTS5 full-text search index. no cap. a base index gets built at package install time, and it contains help text for all PCP metrics from the source tree. then, every night, pmsearch_daily(1) copies that base index and extends it with instance names (disk devices, network interfaces, etc.) from the running system. so it stays fresh 🫶

and the best part? no external services (such as Redis or Valkey) are required. zero. none. we're self-sufficient, periodt.

---

💖 OPTIONS 💖

• -c config, --config=config — pick which config file to use.
• -C, --no-colour — no highlighting in results text. for the monochrome girlies 🖤
• -d, --docid — report the document ID of each search result.
• -i, --info — report search index metrics (that's the document count).
• -n, --indom — do an instance domain related entities search.
• -N N, --number=N — return N, search results at most. (yes, that's how the manpage says it, we keep it 💅)
• -O N, --offset=N — paginated results from given offset.
• -q, --query — do a general text search (this is the default, so if you do nothing, you're doing this).
• -s, --suggest — do 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 🔥

look at her go:

$ 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

ate and left no crumbs fr fr 🌈

---

🎀 FILES 🎀

• $PCP_VAR_DIR/lib/pmsearch.index — the nightly search index (a SQLite FTS5 database), rebuilt by pmsearch_daily(1). this is a copy of the base index extended with runtime instance data. the glow-up version ✨
• $PCP_SHARE_DIR/lib/pmsearch.index — the build-time base index containing all metrics from the PCP source tree. used as a fallback when the nightly index is not yet available. the understudy, but make it useful 💜

---

🧚 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 ngl, the information is sometimes cryptic and primarily intended to provide guidance for developers rather than for end-users. it's giving insider info 🙈

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), pmsearch_daily(1), pmproxy(1), pmlogger(1) and pmlogger_daily(1).

---

and that's the whole page bestie 🫶 this one came to you straight from Performance Co-Pilot (that's PCP, the source/version), and we're signing off on PMSEARCH(1). go search something slay. 💅✨