1PMFIND_CHECK(1)             General Commands Manual            PMFIND_CHECK(1)
2
3
4

NAME

6       pmfind_check - administration of Performance Co-Pilot discovery
7

SYNOPSIS

9       $PCP_BINADM_DIR/pmfind_check [-CNV?]  [-l logfile]
10

DESCRIPTION

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
20       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
28       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
34       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
38       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

OPTIONS

46       The available command line options are:
47
48       -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
53       -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
63       -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
69       -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
77       -?, --help
78            Display usage message and exit.
79

CONFIGURATION

81       The  command line options passed to pmie and pmlogger can be customized
82       via the $PCP_SYSCONFIG_DIR/pmfind configuration file.
83
84       Refer to the pmie_check and pmlogger_check manual pages for details  of
85       the control file format generated by pmfind_check.
86
87       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
92       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
96       # 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

FILES

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
108       $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
114       $PCP_SYSCONFIG_DIR/pmfind
115            default pmie and pmlogger command line arguments, and other param‐
116            eters passed to pmfind.
117
118       $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

PCP ENVIRONMENT

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

SEE ALSO

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).
133
134
135
136Performance Co-Pilot                  PCP                      PMFIND_CHECK(1)
Impressum