Man page for mk-heartbeat

August 24, 2007 – 5:34 pm

MK-HEARTBEAT

Section: User Contributed Perl Documentation (1)
Updated: 2008-06-01
Index
Return to Main Contents

NAME

mk-heartbeat - Monitor MySQL replication delay.

SYNOPSIS

mk-heartbeat -D test –update -h master-server
mk-heartbeat -D test –monitor -h slave-server
mk-heartbeat -D test –monitor -h slave-server –dbidriver Pg

DESCRIPTION

mk-heartbeat is a two-part MySQL and PostgreSQL replication delay monitoring
system that doesn’t require the slave to be working (in other words, it doesn’t
rely on "SHOW SLAVE STATUS" on MySQL). The first part updates a timestamp
every second on the master. You must create a table on the master as follows:



 CREATE TABLE heartbeat (

   id int NOT NULL PRIMARY KEY,

   ts datetime NOT NULL

 );

 INSERT INTO heartbeat(id) VALUES(1);

The "MEMORY" storage engine is suggested, but not required of course, for
MySQL.

Now you connect mk-heartbeat to the master and run it in “–update” mode
to generate the heartbeat. This completes the first part.

The second part is to monitor the slave’s delay with “–monitor” or
“–check”. This works even on daisy-chained slaves to any depth.

mk-heartbeat has a one-second resolution. It depends on the clocks on the
master and slave servers being closely synchronized via NTP. “–update”
checks happen on the edge of the second, and “–monitor” checks happen
halfway between seconds. As long as the servers’ clocks aren’t skewed much
and the replication events are propagating in less than half a second,
mk-heartbeat will report zero seconds of delay.

mk-heartbeat will try to reconnect if the connection has an error, but will
not retry if it can’t get a connection when it first starts.

The “–dbidriver” option lets you use mk-heartbeat to monitor PostgreSQL
as well. It is reported to work well with Slony-1 replication.

DOWNLOADING

You can download Maatkit from the Sourceforge website at
<http://sourceforge.net/projects/maatkit>, or you can get any of the tools
easily with a command like the following:

wget http://www.maatkit.org/get/toolname
or
wget http://www.maatkit.org/trunk/toolname

Where "toolname" can be replaced with the name (or fragment of a name) of any
of the Maatkit tools. Once downloaded, they’re ready to run; no installation is
needed. The first URL gets the latest released version of the tool, and the
second gets the latest trunk code from Subversion.

OPTIONS

Specify at least one of –stop, –update, –monitor, or –check.

–update, –monitor, and –check are mutually exclusive.

–daemonize and –check are mutually exclusive.

–askpass

Prompt for a password when connecting to MySQL.

–charset

short form: -A; type: string

Default character set.

Enables character set settings in Perl and MySQL. If the value is "utf8", sets
Perl’s binmode on STDOUT to utf8, passes the "mysql_enable_utf8" option to
DBD::mysql, and runs "SET NAMES UTF8" after connecting to MySQL. Any other
value sets binmode on STDOUT without the utf8 layer, and runs "SET NAMES" after
connecting to MySQL.

–check

Check slave delay once and exit.

–daemonize

Fork to the background and detach from the shell. POSIX only.

–database

short form: -D; type: string

The database to use for the connection.

–dbidriver

default: mysql; type: string

Specify a driver for the connection; "mysql" and "Pg" are supported.

–defaults-file

short form: -F; type: string

Only read mysql options from the given file. You must give an absolute
pathname.

–file

type: string

Print latest –monitor output to this file.

When “–monitor” is given, prints output to the specified file instead of to
STDOUT. The file is opened, truncated, and closed every interval, so it will
only contain the most recent statistics. Useful when “–daemonize” is given.

–frames

type: string; default: 1m,5m,15m

Timeframes for averages.

Specifies the timeframes over which to calculate moving averages when
“–monitor” is given. Specify as a comma-separated list of numbers with
suffixes. The suffix can be s for seconds, m for minutes, h for hours, or d for
days. The size of the largest frame determines the maximum memory usage, as up
to the specified number of per-second samples are kept in memory to calculate
the averages. You can specify as many timeframes as you like.

–host

short form: -h; type: string

Connect to host.

–interval

short form: -i; type: time; default: 1s

Interval between updates and checks.

How often to check or update values. The updates and checks will happen when
the Unix time (seconds since epoch) is an even multiple of this value. The
suffix is similar to “–frames”.

–monitor

Monitor slave delay continuously.

Specifies that mk-heartbeat should check the slave’s delay every second and
report to STDOUT (or if “–file” is given, to the file instead). The output
is the current delay followed by moving averages over the timeframe given in
“–frames”. For example,



 5s [  0.25s,  0.05s,  0.02s ]

–password

short form: -p; type: string

Password to use when connecting.

–port

short form: -P; type: int

Port number to use for connection.

–quiet

short form: -q

Suppresses normal output.

–recurse

type: int

Check slaves recursively to this depth in “–check” mode.

Try to discover slave servers recursively, to the specified depth. After
discovering servers, run the check on each one of them and print the hostname
(if possible), followed by the slave delay.

This currently works only with MySQL. It uses "SHOW PROCESSLIST" to discover
slaves; if that returns nothing, it falls back to examining the output of "SHOW SLAVE HOSTS" to try to find slaves.

–replace

short form: -r

Use "REPLACE" instead of "UPDATE" for –update.

When running in “–update” mode, use "REPLACE" instead of "UPDATE" to set
the heartbeat table’s timestamp. The "REPLACE" statement is a MySQL extension
to SQL. This option is useful when you don’t know whether the table contains
any rows or not.

–sentinel

type: string; default: /tmp/mk-heartbeat-sentinel

Exit if this file exists.

–setvars

type: string; default: wait_timeout=10000

Set these MySQL variables.

Specify any variables you want to be set immediately after connecting to MySQL.
These will be included in a "SET" command.

–skew

short form: -k; type: int; default: 500000

How long to delay checks, in milliseconds.

The default is to delay checks one half second. Since the update happens as
soon as possible after the beginning of the second on the master, this allows
one half second of replication delay before reporting that the slave lags the
master by one second. If your clocks are not completely accurate or there is
some other reason you’d like to delay the slave more or less, you can tweak this
value. Try setting the "MKDEBUG" environment variable to see the effect this
has.

–socket

short form: -S; type: string

Socket file to use for connection.

–stop

Stop running instances by creating the sentinel file.

This should have the effect of stopping all running
instances which are watching the same sentinel file. If none of
“–update”, “–monitor” or “–check” is specified, "mk-heartbeat"
will exit after creating the file. If one of these is specified,
"mk-heartbeat" will wait the interval given by “–interval”, then remove
the file and continue working.

You might find this handy to stop cron jobs gracefully if necessary, or to
replace one running instance with another. For example, if you want to stop
and restart "mk-heartbeat" every hour (just to make sure that it is restarted
every hour, in case of a server crash or some other problem), you could use a
"crontab" line like this:

0 * * * * mk-heartbeat –update -D test –stop –sentinel /tmp/mk-heartbeatup

The non-default “–sentinel” will make sure the hourly "cron" job stops
only instances previously started with the same options (that is, from the
same "cron" job).

ENVIRONMENT

The environment variable "MKDEBUG" enables verbose debugging output in all of the
Maatkit tools:



   MKDEBUG=1 mk-….

SYSTEM REQUIREMENTS

You need Perl, DBI, DBD::mysql, and some core packages that ought to be
installed in any reasonably new version of Perl.

BUGS

Please use the Sourceforge bug tracker, forums, and mailing lists to request
support or report bugs: <http://sourceforge.net/projects/maatkit/>.

Please include the complete command-line used to reproduce the problem you are
seeing, the version of all MySQL servers involved, the complete output of the
tool when run with “–version”, and if possible, debugging output produced by
running with the "MKDEBUG=1" environment variable.

COPYRIGHT, LICENSE AND WARRANTY

THIS PROGRAM IS PROVIDED “AS IS” AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

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, version 2; OR the Perl Artistic License. On UNIX and similar
systems, you can issue `man perlgpl’ or `man perlartistic’ to read these
licenses.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place, Suite 330, Boston, MA 02111-1307 USA.

AUTHOR

Proven Scaling LLC, SixApart Ltd, and Baron Schwartz.

VERSION

This manual page documents Ver 1.0.9 Distrib 1972 $Revision: 1970 $.

Linux Apache MySQL PHP Tips