MK-HEARTBEAT(1)

📦
version 7540 · 3 versions
, in fedora 43

💖 MK-HEARTBEAT(1) 💖

okay so this is the manual page for mk-heartbeat, filed under User Contributed Perl Documentation, and bestie it is a LOT — so buckle up 🫶

✨ NAME ✨

mk-heartbeat — Monitor MySQL replication delay. that's it. that's the job. and she does it flawlessly 💅

🌸 SYNOPSIS 🌸

Usage: mk-heartbeat [OPTION...] [DSN] --update|--monitor|--check|--stop

mk-heartbeat measures replication lag on a MySQL or PostgreSQL server. You can use it to update a master, or monitor a replica. And if it can, it reads your MySQL connection options straight out of your .my.cnf file. (convenient!! we love a tool that does its own homework 📚)

Start a daemonized process to update the test.heartbeat table on the master:

mk-heartbeat -D test --update -h master-server --daemonize

Monitor replication lag on the slave:

mk-heartbeat -D test --monitor -h slave-server
mk-heartbeat -D test --monitor -h slave-server --dbi-driver Pg

Check slave lag once and exit (using the optional DSN to specify the slave host):

mk-heartbeat -D test --check h=slave-server

🚨 RISKS 🚨

okay so this section exists to tell you about the potential risks — whether known or unknown — of using this tool. The two main categories of risk are: (1) risks that come from the nature of the tool (like, is it read-only or read-write?) and (2) risks that come from bugs. 💀

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

As of this release, we know of no bugs that could cause serious harm to users. (slay, honestly 🎀)

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

See also BUGS for more info 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. And the way it does that matters — it avoids relying on the replication mechanism itself, because that thing is unreliable. (case in point: SHOW SLAVE STATUS on MySQL. 🙈)

Part one: an --update instance of mk-heartbeat that connects to a master and updates a timestamp (the "heartbeat record") every --interval seconds. Since the heartbeat table may contain records from multiple masters (peep MULTI-SLAVE HIERARCHY), the server's ID (@@server_id) is used to identify records.

Part two: a --monitor or --check instance of mk-heartbeat that connects to a slave, examines the replicated heartbeat record from its immediate master (or from the --master-server-id you specified), and computes the difference from the current system time. If replication between the slave and the master is delayed or broken, that computed difference will be greater than zero — and it can potentially keep increasing if --monitor is specified. 📈

You must either manually create the heartbeat table on the master, or use --create-table. (see --create-table for the proper heartbeat table structure.) The MEMORY storage engine is suggested for MySQL, but not required, of course. ✨

The heartbeat table must contain a heartbeat row. By default, a heartbeat row is inserted if it doesn't exist. This feature can be disabled with the --[no]insert-heartbeat-row option, in case the database user does not have INSERT privileges. 🔐

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 like Continuent Tungsten, whatever. 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. (yes, three masters deep, she does not care 💅) 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 maximum resolution of 0.01 second. The clocks on the master and slave servers must be closely synchronized via NTP. By default, --update checks happen on the edge of the second (like 00:01) and --monitor checks happen halfway between seconds (like 00:01.5). As long as the servers' clocks are closely synchronized and 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 it will not retry if it can't get a connection when it first starts. (one shot. main character energy. 🎯)

The --dbi-driver option lets you use mk-heartbeat to monitor PostgreSQL as well. It is reported to work well with Slony-1 replication. 🐘

🦋 MULTI-SLAVE HIERARCHY 🦋

If the replication hierarchy has multiple slaves which are masters of other slaves, like master -> slave1 -> slave2, then --update instances can be ran on the slaves as well as the master. The default heartbeat table (see --create-table) is keyed on the server_id column, so each server will update the row where server_id=@@server_id.

For --monitor and --check, if --master-server-id is not specified, the tool tries to discover and use the slave's immediate master. If that fails, or if you want to monitor lag from another master, then you can specify the --master-server-id to use. 🔍

For example, if the replication hierarchy is master -> slave1 -> slave2 with corresponding server IDs 1, 2 and 3, you can:

mk-heartbeat --daemonize -D test --update -h master
mk-heartbeat --daemonize -D test --update -h slave1

Then check (or monitor) the replication delay from master to slave2:

mk-heartbeat -D test --master-server-id 1 --check slave2

Or check the replication delay from slave1 to slave2:

mk-heartbeat -D test --master-server-id 2 --check slave2

Stopping the --update instance on slave1 will not affect the instance on master. 🛑

👑 MASTER AND SLAVE STATUS 👑

The default heartbeat table (see --create-table) has columns for saving information from SHOW MASTER STATUS and SHOW SLAVE STATUS. These columns are optional. If any are present, their corresponding information will be saved. 💾

💅 OPTIONS 💅

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

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

--daemonize and --check are mutually exclusive.

This tool accepts additional command-line arguments. Refer to the SYNOPSIS and usage information for details.

  • --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. If you also specify --recurse, the tool will try to discover slave's of the given slave and check and print their lag, too. The hostname or IP and port for each slave is printed before its delay. --recurse only works with MySQL. 🔎
  • --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 (
  ts                    varchar(26) NOT NULL,
  server_id             int unsigned NOT NULL PRIMARY KEY,
  file                  varchar(255) DEFAULT NULL,    -- SHOW MASTER STATUS
  position              bigint unsigned DEFAULT NULL, -- SHOW MASTER STATUS
  relay_master_log_file varchar(255) DEFAULT NULL,    -- SHOW SLAVE STATUS
  exec_master_log_pos   bigint unsigned DEFAULT NULL  -- SHOW SLAVE STATUS
);

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 (ts, server_id) VALUES (NOW(), N);

where N is the server's ID; do not use @@server_id, because it will replicate and slaves will insert their own server ID instead of the master's server ID. 🚫

This is done automatically by --create-table.

A legacy version of the heartbeat table is still supported:

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

Legacy tables do not support --update instances on each slave of a multi-slave hierarchy like master -> slave1 -> slave2. To manually insert the one required row into a legacy table:

INSERT INTO heartbeat (id, ts) VALUES (1, NOW());

The tool automatically detects if the heartbeat table is legacy. 🕵️

See also MULTI-SLAVE HIERARCHY.

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

  • --[no]insert-heartbeat-row — default: yes

Insert a heartbeat row in the --table if one doesn't exist.

The heartbeat --table requires a heartbeat row, else there's nothing to --update, --monitor, or --check! By default, the tool will insert a heartbeat row if one is not already present. You can disable this feature by specifying --no-insert-heartbeat-row, in case the database user does not have INSERT privileges. 💌

  • --interval — type: float; default: 1.0

So how often do we update or check the heartbeat --table? 👀 Updates and checks begin on the first whole second, then repeat every --interval seconds for --update and every --interval plus --skew seconds for --monitor. Like, synchronized vibes only. ✨

For example, if at 00:00.4 an --update instance is started at 0.5 second intervals, the first update happens at 00:01.0, the next at 00:01.5, etc. If at 00:10.7 a --monitor instance is started at 0.05 second intervals with the default 0.5 second --skew, then the first check happens at 00:11.5 (00:11.0 + 0.5) which will be --skew seconds after the last update which, because the instances are checking at synchronized intervals, happened at 00:11.0. The math is mathing, bestie. 🧮

The tool waits for and begins on the first whole second just to make the interval calculations simpler. Therefore, the tool could wait up to 1 second before updating or checking. ⏳

The minimum (fastest) interval is 0.01, and the maximum precision is two decimal places, so 0.015 will be rounded to 0.02. precision queen 💅

If a legacy heartbeat table (see --create-table) is used, then the maximum precision is 1s because the ts column is type datetime. 🕰️

  • --log — type: string. Print all output to this file when daemonized. 📝
  • --master-server-id — type: string. Calculate delay from this master server ID for --monitor or --check. If not given, mk-heartbeat attempts to connect to the server's master and determine its server id. 🆔
  • --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. 🔌
  • --print-master-server-id — Print the auto-detected or given --master-server-id. If --check or --monitor is specified, specifying this option will print the auto-detected or given --master-server-id at the end of each line. 🖨️
  • --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. It must be used in conjunction with --update. 🔄
  • --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: float; default: 0.5. How long to delay checks. 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-heartbeat-hourly

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. See --create-table. 🗂️
  • --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 a 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. 🙈

This program is copyright 2007-2011 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 MERCHANTABILITY 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.23 Distrib 7540 $Revision: 7537 $.

💖 And that's a wrap, bestie! This manual is for MK-HEARTBEAT(1), rendered by perl v5.42.0 on 2025-07-24. Stay slay! 💅✨

📦 where this page comes from