MK-HEARTBEAT(1)

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 --dbi-driver Pg

RISKS
The following section is included to inform users about the potential risks, whether known or unknown, of using this tool. The two main categories of risks are those created by the nature of the tool (e.g. read-only tools vs. read-write tools) and those created by bugs.

mk-heartbeat merely reads and writes a single record in a table. It should be very low-risk.

At the time of this release, we know of no bugs that could cause serious harm to users.

The authoritative source for updated information is always the online issue tracking system. Issues that affect this tool will be marked as such. You can see a list of such issues at the following URL: <http://www.maatkit.org/bugs/mk-heartbeat>.

See also "BUGS" for more information on filing bugs and getting help.

DESCRIPTION
mk-heartbeat is a two-part MySQL and PostgreSQL replication delay monitoring system that measures delay by looking at actual replicated data. This avoids reliance on the replication mechanism itself, which is unreliable. (For example, "SHOW SLAVE STATUS" on MySQL).

The first part is an instance of mk-heartbeat that connects to the master and updates a timestamp ("heartbeat record") every second with "--update". The second part is another mk-heartbeat instance that connects to the slave, examines the replicated heartbeat with "--monitor" or "--check", and computes the difference from the current system time. If the slave's replication is delayed or broken, the heartbeat will become stale.

You must either manually create a heartbeat table on the master and insert one row, or use "--create-table". See "--create-table" for the proper heartbeat table structure. The "MEMORY" storage engine is suggested, but not required of course, for MySQL.

mk-heartbeat depends only on the heartbeat record being replicated to the slave, so it works regardless of the replication mechanism (built-in replication, a system such as Continuent Tungsten, etc). It works at any depth in the replication hierarchy; for example, it will reliably report how far a slave lags its master's master's master. And if replication is stopped, it will continue to work and report (accurately!) that the slave is falling further and further behind the master.

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 "--dbi-driver" option lets you use mk-heartbeat to monitor PostgreSQL as well. It is reported to work well with Slony-1 replication.

OPTIONS
Specify at least one of "--stop", "--update", "--monitor", or "--check".

"--update", "--monitor", and "--check" are mutually exclusive.

"--daemonize" and "--check" are mutually exclusive.

--ask-pass
    Prompt for a password when connecting to MySQL.

--charset
    short form: -A; type: string

    Default character set. 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.

--config
    type: Array

    Read this comma-separated list of config files; if specified, this must be the first option on the command line.

--create-table
    Create the heartbeat "--table" if it does not exist.

    This option causes the table specified by "--database" and "--table" to be created with the following MAGIC_create_heartbeat table definition:

     CREATE TABLE heartbeat (
       id int NOT NULL PRIMARY KEY,
       ts datetime NOT NULL
     );

    The heartbeat table requires at least one row. If you manually create the heartbeat table, then you must insert a row by doing:

     INSERT INTO heartbeat (id) VALUES (1);

    This is done automatically by --create-table.

--daemonize
    Fork to the background and detach from the shell. POSIX operating systems only.

--database
    short form: -D; type: string

    The database to use for the connection.

--dbi-driver
    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.

--help
    Show help and exit.

--host
    short form: -h; type: string

    Connect to host.

--interval
    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".

--log
    type: string

    Print all output to this file when daemonized.

--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.

--pid
    type: string

    Create the given PID file when daemonized. The file contains the process ID of the daemonized instance. The PID file is removed when the daemonized instance exits. The program checks for the existence of the PID file when starting; if it exists and the process with the matching PID exists, the program exits.

--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. See "--recursion-method".

--recursion-method
    type: string

    Preferred recursion method used to find slaves.

    Possible methods are:

      METHOD       USES
      ===========  ================
      processlist  SHOW PROCESSLIST
      hosts        SHOW SLAVE HOSTS

    The processlist method is preferred because SHOW SLAVE HOSTS is not reliable. However, the hosts method is required if the server uses a non-standard port (not 3306). Usually mk-heartbeat does the right thing and finds the slaves, but you may give a preferred method and it will be used first. If it doesn't find any slaves, the other methods will be tried.

--replace
    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.

--run-time
    type: time

    Time to run before exiting.

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

    Exit if this file exists.

--set-vars
    type: string; default: wait_timeout=10000

    Set these MySQL variables. Immediately after connecting to MySQL, this string will be appended to SET and executed.

--skew
    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).

    See also "--sentinel".

--table
    type: string; default: heartbeat

    The table to use for the heartbeat.

    Don't specify database.table; use "--database" to specify the database.

--update
    Update a master's heartbeat.

--user
    short form: -u; type: string

    User for login if not current user.

--version
    Show version and exit.

DSN OPTIONS
These DSN options are used to create a DSN. Each option is given like "option=value". The options are case-sensitive, so P and p are not the same option. There cannot be whitespace before or after the "=" and if the value contains whitespace it must be quoted. DSN options are comma-separated. See the maatkit manpage for full details.

•   A

    dsn: charset; copy: yes

    Default character set.

•   D

    dsn: database; copy: yes

    Default database.

•   F

    dsn: mysql_read_default_file; copy: yes

    Only read default options from the given file

•   h

    dsn: host; copy: yes

    Connect to host.

•   p

    dsn: password; copy: yes

    Password to use when connecting.

•   P

    dsn: port; copy: yes

    Port number to use for connection.

•   S

    dsn: mysql_socket; copy: yes

    Socket file to use for connection.

•   u

    dsn: user; copy: yes

    User for login if not current user.

DOWNLOADING
You can download Maatkit from Google Code at <http://code.google.com/p/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.

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
For list of known bugs see <http://www.maatkit.org/bugs/mk-heartbeat>.

Please use Google Code Issues and Groups to report bugs or request support: <http://code.google.com/p/maatkit/>. You can also join #maatkit on Freenode to discuss 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 copyright 2007-2010 Percona Inc. and copyright 2006 Proven Scaling LLC and Six Apart Ltd. Feedback and improvements are welcome.

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.

SEE ALSO
See also mk-slave-delay and mk-slave-restart.

AUTHOR
Proven Scaling LLC, SixApart Ltd, and Baron Schwartz

ABOUT MAATKIT
This tool is part of Maatkit, a toolkit for power users of MySQL. Maatkit was created by Baron Schwartz; Baron and Daniel Nichter are the primary code contributors. Both are employed by Percona. Financial support for Maatkit development is primarily provided by Percona and its clients.

VERSION
This manual page documents Ver 1.0.21 Distrib 6224 $Revision: 6208 $.