1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
'\"macro stdmacro
.\"
.\" Copyright (c) 2020,2024 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMSEARCH 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmsearch\f1 \- help text and names search for metrics, instances and instance domains
.SH SYNOPSIS
\fBpmsearch\fR
[\fB\-CdinqsStTV?\fR]
[\fB\-c\fR \fIconfig\fR]
[\fB\-h\fR \fIhost\fR]
[\fB\-p\fR \fIport\fR]
[\fB\-N\fR \fInumber\fR]
[\fB\-O\fR \fIoffset\fR]
[\fIquery\fR | \fIindom\fR]
.SH DESCRIPTION
.de SAMPLE
.RS 2n
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
..
.B pmsearch
performs full text search queries to find metrics using names
and help text from metrics, instance domains and instances.
.PP
It makes use of capabilities of the Performance Co-Pilot (PCP)
.BR pmproxy (1)
service, the Valkey distributed key-value store and associated
ValkeySearch module.
.PP
Note that in order to use these services, it is
.B mandatory
that
.B pmproxy
is communicating with a Valkey key-value server
that has the
.I valkey-search.so
module loaded.
When configured to do so,
.B 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
.BR pmlogger (1)
and
.BR pmlogger_daily (1)
for further details.
.PP
By default
.B pmsearch
communicates with a local key-value server
however the \fB\-h\fR and \fB\-p\fR 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.
.SH OPTIONS
.TP 5
\fB\-c\fR \fIconfig\fR, \fB\-\-config\fR=\fIconfig\fR
Specify the
.IR config
file to use.
.TP
\fB\-C\fR, \fB\-\-no-colour\fR
No highlighting in results text.
.TP
\fB\-d\fR, \fB\-\-docid\fR
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.
.TP
\fB\-h\fR \fIhost\fR, \fB\-\-host\fR=\fIhost\fR
Connect to the key-value server at
.IR host ,
rather than the one the localhost.
.TP
\fB\-i\fR, \fB\-\-info\fR
Report search engine internal metrics.
.TP
\fB\-n\fR, \fB\-\-indom\fR
Perform an
.IR instance
.IR domain
related entities search
.TP
\fB\-N\fR \fIN\fR, \fB\-\-number\fR=\fIN\fR
Return
.IR N ,
search results at most.
.TP
\fB\-O\fR \fIN\fR, \fB\-\-offset\fR=\fIN\fR
Paginated results from given offset.
.TP
\fB\-p\fR \fIport\fR, \fB\-\-port\fR=\fIport\fR
Connect to the key-value server at
.IR port ,
rather than the default
.BR 6379 .
.TP
\fB\-q\fR, \fB\-\-query\fR
Perform a general text search (default).
.TP
\fB\-s\fR, \fB\-\-suggest\fR
Perform a name suggestion search
.TP
\fB\-S\fR, \fB\-\-score\fR
Report score (rank) of each result.
.TP
\fB\-T\fR, \fB\-\-total\fR
Report total number of of search results.
.TP
\fB\-t\fR, \fB\-\-times\fR
Report elapsed search execution time.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display version number and exit.
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH EXAMPLES
.SAMPLE
$ pmsearch kernel idle
Type: metric
Name: \fBkernel\fR.all.cpu.\fBidle\fR
One line: total \fBidle\fR CPU time from /proc/stat for all CPUs
Type: metric
Name: \fBkernel\fR.all.idletime
One line: time the current \fBkernel\fR has been \fBidle\f1 since boot
Type: metric
Name: \fBkernel\f1.percpu.cpu.\fBidle\fR
InDom: 60.0
One line: percpu \fBidle\fR CPU time metric from /proc/stat
.ESAMPLE
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.PP
For environment variables affecting PCP tools, see \fBpmGetOptions\fP(3).
.SH SEE ALSO
.BR PCPIntro (1),
.BR pmproxy (1),
.BR pmlogger (1)
and
.BR pmlogger_daily (1).
.\" control lines for scripts/man-spell
.\" +ok+ SHA Valkey ValkeySearch hexdigit idletime
.\" +ok+ stat {from /proc/stat}
|
