'\"macro stdmacro
.\"
.\" Copyright (c) 2020 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 capabilties of the Performance Co-Pilot (PCP)
.BR pmproxy (1)
service, the Redis distributed data store, and the RediSearch
module.
.PP
Note that in order to use these services, it is
.B mandatory
that
.B pmproxy
is communicating with a
.BR redis-server (1)
that has the
.I redisearch.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 RediSearch 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
.BR redis-server (1),
however the \fB\-h\fR and \fB\-p\fR options can be used to
specify an alternate Redis instance.
If this instance is a node of a Redis 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 Redis 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\-q\fR, \fB\-\-query\fR
Perform a general text search (default).
.TP
\fB\-s\fR, \fB\-\-suggest\fR
Peform 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),
.BR pmlogger_daily (1)
and
.BR redis-server (1).