1PMFIND_CHECK(1) General Commands Manual PMFIND_CHECK(1)
2
6 pmfind_check - administration of Performance Co-Pilot discovery
7
9 $PCP_BINADM_DIR/pmfind_check [-CNV?] [-l logfile]
10
12 This shell script is used to integrate the Performance Co-Pilot (see
13 PCPIntro(1)) collector service discovery mechanisms with pmie(1) and
14 pmlogger(1) service administration, such that multiple collector hosts
15 can be monitored from a single centralized host. It is important to
16 note that the pmfind service is tightly integrated with the pmie and
17 pmlogger services, and these must also be enabled if the services are
18 to be started for each collector system that pmfind discovers.
19 pmfind_check is designed to be enabled via a service management daemon
21 such as systemd(1) on Linux. It is run from a system timer (either by
22 systemd or by cron on other systems). Once per timer interval pmfind
23 attempts discovery of PCP collector systems. For each unique system
24 found pmfind_check creates pmie_check and pmlogger_check control file
25 entries, such that these latter process can manage one pmie and pmlog‐
26 ger service for each discovered collector system.
27 When run through systemd these processes will be launched immediately
29 because systemd monitors the service control files for changes. With
30 systemd one may also initiate an immediate service discovery with
31 pmfind and pmfind_check by modifying the $PCP_SYSCONF_DIR/pmfind direc‐
32 tory in any way.
33 When run from cron the next (also timer-based) invocation of pmie_check
35 or pmlogger_check will start and manage the associated pmie and pmlog‐
36 ger processes.
37 The control file entries created by pmfind_check follow the convention
39 of individual files for each collector host. The files are named using
40 the (unique) source identifier that pmfind calculates. This identifier
41 is a hash calculated based on (non-optional) context labels available
42 from every collector host, and is the same source identifier reported
43 and used by pminfo(1) and pmseries(1).
44
46 The available command line options are:
47 -C, --containers
49 This option causes pmfind_check to query each discovered collector
50 system for running containers as well, which will then be individ‐
51 ually monitored.
52 -l file, --logfile=file
54 In order to ensure that mail is not unintentionally sent when
55 these scripts are run from cron(8) diagnostics are always sent to
56 log files. By default, this file is
57 $PCP_LOG_DIR/pmfind/pmfind_check.log but this can be changed using
58 the -l option. If this log file already exists when the script
59 starts, it will be renamed with a .prev suffix (overwriting any
60 log file saved earlier) before diagnostics are generated to the
61 new log file.
62 -N, --showme
64 This option enables a ``show me'' mode, where the programs actions
65 are echoed, but not executed, in the style of ``make -n''. Using
66 -N in conjunction with -V maximizes the diagnostic capabilities
67 for debugging.
68 -V, --verbose
70 The output from the cron execution of the scripts may be extended
71 using the -V option to the scripts which will enable verbose trac‐
72 ing of their activity. By default the scripts generate no output
73 unless some error or warning condition is encountered. Using -N
74 in conjunction with -V maximizes the diagnostic capabilities for
75 debugging.
76 -?, --help
78 Display usage message and exit.
79
81 The command line options passed to pmie and pmlogger can be customized
82 via the $PCP_SYSCONFIG_DIR/pmfind configuration file.
83 Refer to the pmie_check and pmlogger_check manual pages for details of
85 the control file format generated by pmfind_check.
86 By default, each collector system pmie logfile will be created in
88 $PCP_LOG_DIR/pmie/source and pmlogger archives will be created below
89 $PCP_ARCHIVE_DIR/source. This is consistent with the way pmie(1) and
90 pmlogger(1) maintain their activity logs and archive files.
91 Typical crontab(5) entries for periodic execution of pmfind_check are
93 given in $PCP_SYSCONF_DIR/pmfind/crontab (unless installed by default
94 in /etc/cron.d already) and shown below.
95 # every minute, discover remote PCP services
97 * * * * * $PCP_BINADM_DIR/pmfind_check
98 When using systemd(1) on Linux, no crontab entries are needed as the
99 timer and path mechanisms provided by systemd are used instead.
100
102 $PCP_PMIECONTROL_PATH.d
103 PCP inference engine control files for each discovered metric
104 source, typically one per host or container.
105 Warning: this files herein must not be writable by any user other
106 than root.
107 $PCP_PMLOGGERCONTROL_PATH.d
109 PCP logger control files for each discovered metric source, typi‐
110 cally one per host or container.
111 Warning: this files herein must not be writable by any user other
112 than root.
113 $PCP_SYSCONFIG_DIR/pmfind
115 default pmie and pmlogger command line arguments, and other param‐
116 eters passed to pmfind.
117 $PCP_SYSCONF_DIR/pmfind/crontab
119 sample crontab for automated script execution by root - exists
120 only if the platform does not support the /etc/cron.d mechanism.
121
123 Environment variables with the prefix PCP_ are used to parameterize the
124 file and directory names used by PCP. On each installation, the file
125 /etc/pcp.conf contains the local values for these variables. The
126 $PCP_CONF variable may be used to specify an alternative configuration
127 file, as described in pcp.conf(5).
128
130 PCPIntro(1), pmcd(1), pmfind(1), pmie(1), pmie_check(1), pminfo(1), pm‐
131 logger(1), pmlogger_check(1), pmseries(1), systemd(1), crontab(5), and
132 cron(8).
133Performance Co-Pilot PCP PMFIND_CHECK(1)