1MK-HEARTBEAT(1) User Contributed Perl Documentation MK-HEARTBEAT(1)
2
6 mk-heartbeat - Monitor MySQL replication delay.
7
9 mk-heartbeat -D test --update -h master-server
10 mk-heartbeat -D test --monitor -h slave-server
11 mk-heartbeat -D test --monitor -h slave-server --dbi-driver Pg
12
14 The following section is included to inform users about the potential
15 risks, whether known or unknown, of using this tool. The two main
16 categories of risks are those created by the nature of the tool (e.g.
17 read-only tools vs. read-write tools) and those created by bugs.
18 mk-heartbeat merely reads and writes a single record in a table. It
20 should be very low-risk.
21 At the time of this release, we know of no bugs that could cause
23 serious harm to users.
24 The authoritative source for updated information is always the online
26 issue tracking system. Issues that affect this tool will be marked as
27 such. You can see a list of such issues at the following URL:
28 http://www.maatkit.org/bugs/mk-heartbeat
29 <http://www.maatkit.org/bugs/mk-heartbeat>.
30 See also "BUGS" for more information on filing bugs and getting help.
32
34 mk-heartbeat is a two-part MySQL and PostgreSQL replication delay
35 monitoring system that measures delay by looking at actual replicated
36 data. This avoids reliance on the replication mechanism itself, which
37 is unreliable. (For example, "SHOW SLAVE STATUS" on MySQL).
38 The first part is an instance of mk-heartbeat that connects to the
40 master and updates a timestamp ("heartbeat record") every second with
41 "--update". The second part is another mk-heartbeat instance that
42 connects to the slave, examines the replicated heartbeat with
43 "--monitor" or "--check", and computes the difference from the current
44 system time. If the slave's replication is delayed or broken, the
45 heartbeat will become stale.
46 You must either manually create a heartbeat table on the master and
48 insert one row, or use "--create-table". See "--create-table" for the
49 proper heartbeat table structure. The "MEMORY" storage engine is
50 suggested, but not required of course, for MySQL.
51 mk-heartbeat depends only on the heartbeat record being replicated to
53 the slave, so it works regardless of the replication mechanism (built-
54 in replication, a system such as Continuent Tungsten, etc). It works
55 at any depth in the replication hierarchy; for example, it will
56 reliably report how far a slave lags its master's master's master. And
57 if replication is stopped, it will continue to work and report
58 (accurately!) that the slave is falling further and further behind the
59 master.
60 mk-heartbeat has a one-second resolution. It depends on the clocks on
62 the master and slave servers being closely synchronized via NTP.
63 "--update" checks happen on the edge of the second, and "--monitor"
64 checks happen halfway between seconds. As long as the servers' clocks
65 aren't skewed much and the replication events are propagating in less
66 than half a second, mk-heartbeat will report zero seconds of delay.
67 mk-heartbeat will try to reconnect if the connection has an error, but
69 will not retry if it can't get a connection when it first starts.
70 The "--dbi-driver" option lets you use mk-heartbeat to monitor
72 PostgreSQL as well. It is reported to work well with Slony-1
73 replication.
74
76 Specify at least one of "--stop", "--update", "--monitor", or
77 "--check".
78 "--update", "--monitor", and "--check" are mutually exclusive.
80 "--daemonize" and "--check" are mutually exclusive.
82 --ask-pass
84 Prompt for a password when connecting to MySQL.
85 --charset
87 short form: -A; type: string
88 Default character set. If the value is utf8, sets Perl's binmode
90 on STDOUT to utf8, passes the mysql_enable_utf8 option to
91 DBD::mysql, and runs SET NAMES UTF8 after connecting to MySQL. Any
92 other value sets binmode on STDOUT without the utf8 layer, and runs
93 SET NAMES after connecting to MySQL.
94 --check
96 Check slave delay once and exit.
97 --config
99 type: Array
100 Read this comma-separated list of config files; if specified, this
102 must be the first option on the command line.
103 --create-table
105 Create the heartbeat "--table" if it does not exist.
106 This option causes the table specified by "--database" and
108 "--table" to be created with the following MAGIC_create_heartbeat
109 table definition:
110 CREATE TABLE heartbeat (
112 id int NOT NULL PRIMARY KEY,
113 ts datetime NOT NULL
114 );
115 The heartbeat table requires at least one row. If you manually
117 create the heartbeat table, then you must insert a row by doing:
118 INSERT INTO heartbeat (id) VALUES (1);
120 This is done automatically by --create-table.
122 --daemonize
124 Fork to the background and detach from the shell. POSIX operating
125 systems only.
126 --database
128 short form: -D; type: string
129 The database to use for the connection.
131 --dbi-driver
133 default: mysql; type: string
134 Specify a driver for the connection; "mysql" and "Pg" are
136 supported.
137 --defaults-file
139 short form: -F; type: string
140 Only read mysql options from the given file. You must give an
142 absolute pathname.
143 --file
145 type: string
146 Print latest "--monitor" output to this file.
148 When "--monitor" is given, prints output to the specified file
150 instead of to STDOUT. The file is opened, truncated, and closed
151 every interval, so it will only contain the most recent statistics.
152 Useful when "--daemonize" is given.
153 --frames
155 type: string; default: 1m,5m,15m
156 Timeframes for averages.
158 Specifies the timeframes over which to calculate moving averages
160 when "--monitor" is given. Specify as a comma-separated list of
161 numbers with suffixes. The suffix can be s for seconds, m for
162 minutes, h for hours, or d for days. The size of the largest frame
163 determines the maximum memory usage, as up to the specified number
164 of per-second samples are kept in memory to calculate the averages.
165 You can specify as many timeframes as you like.
166 --help
168 Show help and exit.
169 --host
171 short form: -h; type: string
172 Connect to host.
174 --interval
176 type: time; default: 1s
177 Interval between updates and checks.
179 How often to check or update values. The updates and checks will
181 happen when the Unix time (seconds since epoch) is an even multiple
182 of this value. The suffix is similar to "--frames".
183 --log
185 type: string
186 Print all output to this file when daemonized.
188 --monitor
190 Monitor slave delay continuously.
191 Specifies that mk-heartbeat should check the slave's delay every
193 second and report to STDOUT (or if "--file" is given, to the file
194 instead). The output is the current delay followed by moving
195 averages over the timeframe given in "--frames". For example,
196 5s [ 0.25s, 0.05s, 0.02s ]
198 --password
200 short form: -p; type: string
201 Password to use when connecting.
203 --pid
205 type: string
206 Create the given PID file when daemonized. The file contains the
208 process ID of the daemonized instance. The PID file is removed
209 when the daemonized instance exits. The program checks for the
210 existence of the PID file when starting; if it exists and the
211 process with the matching PID exists, the program exits.
212 --port
214 short form: -P; type: int
215 Port number to use for connection.
217 --quiet
219 short form: -q
220 Suppresses normal output.
222 --recurse
224 type: int
225 Check slaves recursively to this depth in "--check" mode.
227 Try to discover slave servers recursively, to the specified depth.
229 After discovering servers, run the check on each one of them and
230 print the hostname (if possible), followed by the slave delay.
231 This currently works only with MySQL. See "--recursion-method".
233 --recursion-method
235 type: string
236 Preferred recursion method used to find slaves.
238 Possible methods are:
240 METHOD USES
242 =========== ================
243 processlist SHOW PROCESSLIST
244 hosts SHOW SLAVE HOSTS
245 The processlist method is preferred because SHOW SLAVE HOSTS is not
247 reliable. However, the hosts method is required if the server uses
248 a non-standard port (not 3306). Usually mk-heartbeat does the
249 right thing and finds the slaves, but you may give a preferred
250 method and it will be used first. If it doesn't find any slaves,
251 the other methods will be tried.
252 --replace
254 Use "REPLACE" instead of "UPDATE" for --update.
255 When running in "--update" mode, use "REPLACE" instead of "UPDATE"
257 to set the heartbeat table's timestamp. The "REPLACE" statement is
258 a MySQL extension to SQL. This option is useful when you don't
259 know whether the table contains any rows or not.
260 --run-time
262 type: time
263 Time to run before exiting.
265 --sentinel
267 type: string; default: /tmp/mk-heartbeat-sentinel
268 Exit if this file exists.
270 --set-vars
272 type: string; default: wait_timeout=10000
273 Set these MySQL variables. Immediately after connecting to MySQL,
275 this string will be appended to SET and executed.
276 --skew
278 type: int; default: 500000
279 How long to delay checks, in milliseconds.
281 The default is to delay checks one half second. Since the update
283 happens as soon as possible after the beginning of the second on
284 the master, this allows one half second of replication delay before
285 reporting that the slave lags the master by one second. If your
286 clocks are not completely accurate or there is some other reason
287 you'd like to delay the slave more or less, you can tweak this
288 value. Try setting the "MKDEBUG" environment variable to see the
289 effect this has.
290 --socket
292 short form: -S; type: string
293 Socket file to use for connection.
295 --stop
297 Stop running instances by creating the sentinel file.
298 This should have the effect of stopping all running instances which
300 are watching the same sentinel file. If none of "--update",
301 "--monitor" or "--check" is specified, "mk-heartbeat" will exit
302 after creating the file. If one of these is specified,
303 "mk-heartbeat" will wait the interval given by "--interval", then
304 remove the file and continue working.
305 You might find this handy to stop cron jobs gracefully if
307 necessary, or to replace one running instance with another. For
308 example, if you want to stop and restart "mk-heartbeat" every hour
309 (just to make sure that it is restarted every hour, in case of a
310 server crash or some other problem), you could use a "crontab" line
311 like this:
312 0 * * * * mk-heartbeat --update -D test --stop \
314 --sentinel /tmp/mk-heartbeat-hourly
315 The non-default "--sentinel" will make sure the hourly "cron" job
317 stops only instances previously started with the same options (that
318 is, from the same "cron" job).
319 See also "--sentinel".
321 --table
323 type: string; default: heartbeat
324 The table to use for the heartbeat.
326 Don't specify database.table; use "--database" to specify the
328 database.
329 --update
331 Update a master's heartbeat.
332 --user
334 short form: -u; type: string
335 User for login if not current user.
337 --version
339 Show version and exit.
340
342 These DSN options are used to create a DSN. Each option is given like
343 "option=value". The options are case-sensitive, so P and p are not the
344 same option. There cannot be whitespace before or after the "=" and if
345 the value contains whitespace it must be quoted. DSN options are
346 comma-separated. See the maatkit manpage for full details.
347 · A
349 dsn: charset; copy: yes
351 Default character set.
353 · D
355 dsn: database; copy: yes
357 Default database.
359 · F
361 dsn: mysql_read_default_file; copy: yes
363 Only read default options from the given file
365 · h
367 dsn: host; copy: yes
369 Connect to host.
371 · p
373 dsn: password; copy: yes
375 Password to use when connecting.
377 · P
379 dsn: port; copy: yes
381 Port number to use for connection.
383 · S
385 dsn: mysql_socket; copy: yes
387 Socket file to use for connection.
389 · u
391 dsn: user; copy: yes
393 User for login if not current user.
395
397 You can download Maatkit from Google Code at
398 <http://code.google.com/p/maatkit/>, or you can get any of the tools
399 easily with a command like the following:
400 wget http://www.maatkit.org/get/toolname
402 or
403 wget http://www.maatkit.org/trunk/toolname
404 Where "toolname" can be replaced with the name (or fragment of a name)
406 of any of the Maatkit tools. Once downloaded, they're ready to run; no
407 installation is needed. The first URL gets the latest released version
408 of the tool, and the second gets the latest trunk code from Subversion.
409
411 The environment variable "MKDEBUG" enables verbose debugging output in
412 all of the Maatkit tools:
413 MKDEBUG=1 mk-....
415
417 You need Perl, DBI, DBD::mysql, and some core packages that ought to be
418 installed in any reasonably new version of Perl.
419
421 For list of known bugs see http://www.maatkit.org/bugs/mk-heartbeat
422 <http://www.maatkit.org/bugs/mk-heartbeat>.
423 Please use Google Code Issues and Groups to report bugs or request
425 support: <http://code.google.com/p/maatkit/>. You can also join
426 #maatkit on Freenode to discuss Maatkit.
427 Please include the complete command-line used to reproduce the problem
429 you are seeing, the version of all MySQL servers involved, the complete
430 output of the tool when run with "--version", and if possible,
431 debugging output produced by running with the "MKDEBUG=1" environment
432 variable.
433
435 This program is copyright 2007-2010 Percona Inc. and copyright 2006
436 Proven Scaling LLC and Six Apart Ltd. Feedback and improvements are
437 welcome.
438 THIS PROGRAM IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
440 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
441 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
442 This program is free software; you can redistribute it and/or modify it
444 under the terms of the GNU General Public License as published by the
445 Free Software Foundation, version 2; OR the Perl Artistic License. On
446 UNIX and similar systems, you can issue `man perlgpl' or `man
447 perlartistic' to read these licenses.
448 You should have received a copy of the GNU General Public License along
450 with this program; if not, write to the Free Software Foundation, Inc.,
451 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
452
454 See also mk-slave-delay and mk-slave-restart.
455
457 Proven Scaling LLC, SixApart Ltd, and Baron Schwartz
458
460 This tool is part of Maatkit, a toolkit for power users of MySQL.
461 Maatkit was created by Baron Schwartz; Baron and Daniel Nichter are the
462 primary code contributors. Both are employed by Percona. Financial
463 support for Maatkit development is primarily provided by Percona and
464 its clients.
465
467 This manual page documents Ver 1.0.22 Distrib 6839 $Revision: 6831 $.
468perl v5.12.1 2010-08-01 MK-HEARTBEAT(1)