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 This option causes pmfind_check to query each discovered collector
49 system for running containers as well, which will then be individ‐
50 ually monitored.
51 -l file, --logfile=file
53 In order to ensure that mail is not unintentionally sent when
54 these scripts are run from cron(8) diagnostics are always sent to
55 log files. By default, this file is
56 $PCP_LOG_DIR/pmfind/pmfind_check.log but this can be changed using
57 the -l option. If this log file already exists when the script
58 starts, it will be renamed with a .prev suffix (overwriting any
59 log file saved earlier) before diagnostics are generated to the
60 new log file.
61 -N, --showme
63 This option enables a ``show me'' mode, where the programs actions
64 are echoed, but not executed, in the style of ``make -n''. Using
65 -N in conjunction with -V maximizes the diagnostic capabilities
66 for debugging.
67 -V, --verbose
69 The output from the cron execution of the scripts may be extended
70 using the -V option to the scripts which will enable verbose trac‐
71 ing of their activity. By default the scripts generate no output
72 unless some error or warning condition is encountered. Using -N
73 in conjunction with -V maximizes the diagnostic capabilities for
74 debugging.
75 -?, --help
77 Display usage message and exit.
78
80 The command line options passed to pmie and pmlogger can be customized
81 via the $PCP_SYSCONFIG_DIR/pmfind configuration file.
82 Refer to the pmie_check and pmlogger_check manual pages for details of
84 the control file format generated by pmfind_check.
85 By default, each collector system pmie logfile will be created in
87 $PCP_LOG_DIR/pmie/source and pmlogger archives will be created below
88 $PCP_ARCHIVE_DIR/source. This is consistent with the way pmie(1) and
89 pmlogger(1) maintain their activity logs and archive files.
90 Typical crontab(5) entries for periodic execution of pmfind_check are
92 given in $PCP_SYSCONF_DIR/pmfind/crontab (unless installed by default
93 in /etc/cron.d already) and shown below.
94 # every minute, discover remote PCP services
96 * * * * * $PCP_BINADM_DIR/pmfind_check
97 When using systemd(1) on Linux, no crontab entries are needed as the
98 timer and path mechanisms provided by systemd are used instead.
99
101 $PCP_PMIECONTROL_PATH.d
102 PCP inference engine control files for each discovered metric
103 source, typically one per host or container.
104 Warning: this files herein must not be writable by any user other
105 than root.
106 $PCP_PMLOGGERCONTROL_PATH.d
108 PCP logger control files for each discovered metric source, typi‐
109 cally one per host or container.
110 Warning: this files herein must not be writable by any user other
111 than root.
112 $PCP_SYSCONFIG_DIR/pmfind
114 default pmie and pmlogger command line arguments, and other param‐
115 eters passed to pmfind.
116 $PCP_SYSCONF_DIR/pmfind/crontab
118 sample crontab for automated script execution by root - exists
119 only if the platform does not support the /etc/cron.d mechanism.
120
122 Environment variables with the prefix PCP_ are used to parameterize the
123 file and directory names used by PCP. On each installation, the file
124 /etc/pcp.conf contains the local values for these variables. The
125 $PCP_CONF variable may be used to specify an alternative configuration
126 file, as described in pcp.conf(5).
127
129 PCPIntro(1), pmcd(1), pmfind(1), pmie(1), pmie_check(1), pminfo(1),
130 pmlogger(1), pmlogger_check(1), pmseries(1), systemd(1), crontab(5),
131 and cron(8).
132Performance Co-Pilot PCP PMFIND_CHECK(1)