.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "PT-HEARTBEAT 1p" .TH PT-HEARTBEAT 1p "2012-06-15" "perl v5.14.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" pt\-heartbeat \- Monitor MySQL replication delay. .SH "SYNOPSIS" .IX Header "SYNOPSIS" Usage: pt-heartbeat [\s-1OPTION\s0...] [\s-1DSN\s0] \-\-update|\-\-monitor|\-\-check|\-\-stop .PP pt-heartbeat measures replication lag on a MySQL or PostgreSQL server. You can use it to update a master or monitor a replica. If possible, MySQL connection options are read from your .my.cnf file. .PP Start daemonized process to update test.heartbeat table on master: .PP .Vb 1 \& pt\-heartbeat \-D test \-\-update \-h master\-server \-\-daemonize .Ve .PP Monitor replication lag on slave: .PP .Vb 1 \& pt\-heartbeat \-D test \-\-monitor \-h slave\-server \& \& pt\-heartbeat \-D test \-\-monitor \-h slave\-server \-\-dbi\-driver Pg .Ve .PP Check slave lag once and exit (using optional \s-1DSN\s0 to specify slave host): .PP .Vb 1 \& pt\-heartbeat \-D test \-\-check h=slave\-server .Ve .SH "RISKS" .IX Header "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. .PP pt-heartbeat merely reads and writes a single record in a table. It should be very low-risk. .PP At the time of this release, we know of no bugs that could cause serious harm to users. .PP 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 \s-1URL:\s0 http://www.percona.com/bugs/pt\-heartbeat . .PP See also \*(L"\s-1BUGS\s0\*(R" for more information on filing bugs and getting help. .SH "DESCRIPTION" .IX Header "DESCRIPTION" pt-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, \f(CW\*(C`SHOW SLAVE STATUS\*(C'\fR on MySQL). .PP The first part is an \*(L"\-\-update\*(R" instance of pt-heartbeat that connects to a master and updates a timestamp (\*(L"heartbeat record\*(R") every \*(L"\-\-interval\*(R" seconds. Since the heartbeat table may contain records from multiple masters (see \*(L"MULTI-SLAVE \s-1HIERARCHY\s0\*(R"), the server's \s-1ID\s0 (@@server_id) is used to identify records. .PP The second part is a \*(L"\-\-monitor\*(R" or \*(L"\-\-check\*(R" instance of pt-heartbeat that connects to a slave, examines the replicated heartbeat record from its immediate master or the specified \*(L"\-\-master\-server\-id\*(R", and computes the difference from the current system time. If replication between the slave and the master is delayed or broken, the computed difference will be greater than zero and potentially increase if \*(L"\-\-monitor\*(R" is specified. .PP You must either manually create the heartbeat table on the master or use \&\*(L"\-\-create\-table\*(R". See \*(L"\-\-create\-table\*(R" for the proper heartbeat table structure. The \f(CW\*(C`MEMORY\*(C'\fR storage engine is suggested, but not required of course, for MySQL. .PP 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 \&\*(L"\-\-[no]insert\-heartbeat\-row\*(R" option in case the database user does not have \s-1INSERT\s0 privileges. .PP pt-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. .PP pt-heartbeat has a maximum resolution of 0.01 second. The clocks on the master and slave servers must be closely synchronized via \s-1NTP\s0. By default, \&\*(L"\-\-update\*(R" checks happen on the edge of the second (e.g. 00:01) and \&\*(L"\-\-monitor\*(R" checks happen halfway between seconds (e.g. 00:01.5). As long as the servers' clocks are closely synchronized and replication events are propagating in less than half a second, pt-heartbeat will report zero seconds of delay. .PP pt-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. .PP The \*(L"\-\-dbi\-driver\*(R" option lets you use pt-heartbeat to monitor PostgreSQL as well. It is reported to work well with Slony\-1 replication. .SH "MULTI-SLAVE HIERARCHY" .IX Header "MULTI-SLAVE HIERARCHY" If the replication hierarchy has multiple slaves which are masters of other slaves, like \*(L"master \-> slave1 \-> slave2\*(R", \*(L"\-\-update\*(R" instances can be ran on the slaves as well as the master. The default heartbeat table (see \*(L"\-\-create\-table\*(R") is keyed on the \f(CW\*(C`server_id\*(C'\fR column, so each server will update the row where \f(CW\*(C`server_id=@@server_id\*(C'\fR. .PP For \*(L"\-\-monitor\*(R" and \*(L"\-\-check\*(R", if \*(L"\-\-master\-server\-id\*(R" is not specified, the tool tries to discover and use the slave's immediate master. If this fails, or if you want monitor lag from another master, then you can specify the \*(L"\-\-master\-server\-id\*(R" to use. .PP For example, if the replication hierarchy is \*(L"master \-> slave1 \-> slave2\*(R" with corresponding server IDs 1, 2 and 3, you can: .PP .Vb 2 \& pt\-heartbeat \-\-daemonize \-D test \-\-update \-h master \& pt\-heartbeat \-\-daemonize \-D test \-\-update \-h slave1 .Ve .PP Then check (or monitor) the replication delay from master to slave2: .PP .Vb 1 \& pt\-heartbeat \-D test \-\-master\-server\-id 1 \-\-check slave2 .Ve .PP Or check the replication delay from slave1 to slave2: .PP .Vb 1 \& pt\-heartbeat \-D test \-\-master\-server\-id 2 \-\-check slave2 .Ve .PP Stopping the \*(L"\-\-update\*(R" instance one slave1 will not affect the instance on master. .SH "MASTER AND SLAVE STATUS" .IX Header "MASTER AND SLAVE STATUS" The default heartbeat table (see \*(L"\-\-create\-table\*(R") has columns for saving information from \f(CW\*(C`SHOW MASTER STATUS\*(C'\fR and \f(CW\*(C`SHOW SLAVE STATUS\*(C'\fR. These columns are optional. If any are present, their corresponding information will be saved. .SH "OPTIONS" .IX Header "OPTIONS" Specify at least one of \*(L"\-\-stop\*(R", \*(L"\-\-update\*(R", \*(L"\-\-monitor\*(R", or \*(L"\-\-check\*(R". .PP \&\*(L"\-\-update\*(R", \*(L"\-\-monitor\*(R", and \*(L"\-\-check\*(R" are mutually exclusive. .PP \&\*(L"\-\-daemonize\*(R" and \*(L"\-\-check\*(R" are mutually exclusive. .PP This tool accepts additional command-line arguments. Refer to the \&\*(L"\s-1SYNOPSIS\s0\*(R" and usage information for details. .IP "\-\-ask\-pass" 4 .IX Item "--ask-pass" Prompt for a password when connecting to MySQL. .IP "\-\-charset" 4 .IX Item "--charset" short form: \-A; type: string .Sp Default character set. If the value is utf8, sets Perl's binmode on \s-1STDOUT\s0 to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and runs \s-1SET\s0 \s-1NAMES\s0 \s-1UTF8\s0 after connecting to MySQL. Any other value sets binmode on \s-1STDOUT\s0 without the utf8 layer, and runs \s-1SET\s0 \s-1NAMES\s0 after connecting to MySQL. .IP "\-\-check" 4 .IX Item "--check" Check slave delay once and exit. If you also specify \*(L"\-\-recurse\*(R", the tool will try to discover slave's of the given slave and check and print their lag, too. The hostname or \s-1IP\s0 and port for each slave is printed before its delay. \*(L"\-\-recurse\*(R" only works with MySQL. .IP "\-\-config" 4 .IX Item "--config" type: Array .Sp Read this comma-separated list of config files; if specified, this must be the first option on the command line. .IP "\-\-create\-table" 4 .IX Item "--create-table" Create the heartbeat \*(L"\-\-table\*(R" if it does not exist. .Sp This option causes the table specified by \*(L"\-\-database\*(R" and \*(L"\-\-table\*(R" to be created with the following MAGIC_create_heartbeat table definition: .Sp .Vb 8 \& 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 \& ); .Ve .Sp The heartbeat table requires at least one row. If you manually create the heartbeat table, then you must insert a row by doing: .Sp .Vb 1 \& INSERT INTO heartbeat (ts, server_id) VALUES (NOW(), N); .Ve .Sp where \f(CW\*(C`N\*(C'\fR is the server's \s-1ID\s0; do not use @@server_id because it will replicate and slaves will insert their own server \s-1ID\s0 instead of the master's server \s-1ID\s0. .Sp This is done automatically by \*(L"\-\-create\-table\*(R". .Sp A legacy version of the heartbeat table is still supported: .Sp .Vb 4 \& CREATE TABLE heartbeat ( \& id int NOT NULL PRIMARY KEY, \& ts datetime NOT NULL \& ); .Ve .Sp Legacy tables do not support \*(L"\-\-update\*(R" instances on each slave of a multi-slave hierarchy like \*(L"master \-> slave1 \-> slave2\*(R". To manually insert the one required row into a legacy table: .Sp .Vb 1 \& INSERT INTO heartbeat (id, ts) VALUES (1, NOW()); .Ve .Sp The tool automatically detects if the heartbeat table is legacy. .Sp See also \*(L"MULTI-SLAVE \s-1HIERARCHY\s0\*(R". .IP "\-\-daemonize" 4 .IX Item "--daemonize" Fork to the background and detach from the shell. \s-1POSIX\s0 operating systems only. .IP "\-\-database" 4 .IX Item "--database" short form: \-D; type: string .Sp The database to use for the connection. .IP "\-\-dbi\-driver" 4 .IX Item "--dbi-driver" default: mysql; type: string .Sp Specify a driver for the connection; \f(CW\*(C`mysql\*(C'\fR and \f(CW\*(C`Pg\*(C'\fR are supported. .IP "\-\-defaults\-file" 4 .IX Item "--defaults-file" short form: \-F; type: string .Sp Only read mysql options from the given file. You must give an absolute pathname. .IP "\-\-file" 4 .IX Item "--file" type: string .Sp Print latest \*(L"\-\-monitor\*(R" output to this file. .Sp When \*(L"\-\-monitor\*(R" is given, prints output to the specified file instead of to \&\s-1STDOUT\s0. The file is opened, truncated, and closed every interval, so it will only contain the most recent statistics. Useful when \*(L"\-\-daemonize\*(R" is given. .IP "\-\-frames" 4 .IX Item "--frames" type: string; default: 1m,5m,15m .Sp Timeframes for averages. .Sp Specifies the timeframes over which to calculate moving averages when \&\*(L"\-\-monitor\*(R" 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. .IP "\-\-help" 4 .IX Item "--help" Show help and exit. .IP "\-\-host" 4 .IX Item "--host" short form: \-h; type: string .Sp Connect to host. .IP "\-\-[no]insert\-heartbeat\-row" 4 .IX Item "--[no]insert-heartbeat-row" default: yes .Sp Insert a heartbeat row in the \*(L"\-\-table\*(R" if one doesn't exist. .Sp The heartbeat \*(L"\-\-table\*(R" requires a heartbeat row, else there's nothing to \*(L"\-\-update\*(R", \*(L"\-\-monitor\*(R", or \*(L"\-\-check\*(R"! By default, the tool will insert a heartbeat row if one is not already present. You can disable this feature by specifying \f(CW\*(C`\-\-no\-insert\-heartbeat\-row\*(C'\fR in case the database user does not have \s-1INSERT\s0 privileges. .IP "\-\-interval" 4 .IX Item "--interval" type: float; default: 1.0 .Sp How often to update or check the heartbeat \*(L"\-\-table\*(R". Updates and checks begin on the first whole second then repeat every \*(L"\-\-interval\*(R" seconds for \*(L"\-\-update\*(R" and every \*(L"\-\-interval\*(R" plus \*(L"\-\-skew\*(R" seconds for \&\*(L"\-\-monitor\*(R". .Sp For example, if at 00:00.4 an \*(L"\-\-update\*(R" 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 \*(L"\-\-monitor\*(R" instance is started at 0.05 second intervals with the default 0.5 second \*(L"\-\-skew\*(R", then the first check happens at 00:11.5 (00:11.0 + 0.5) which will be \*(L"\-\-skew\*(R" seconds after the last update which, because the instances are checking at synchronized intervals, happened at 00:11.0. .Sp 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. .Sp The minimum (fastest) interval is 0.01, and the maximum precision is two decimal places, so 0.015 will be rounded to 0.02. .Sp If a legacy heartbeat table (see \*(L"\-\-create\-table\*(R") is used, then the maximum precision is 1s because the \f(CW\*(C`ts\*(C'\fR column is type \f(CW\*(C`datetime\*(C'\fR. .IP "\-\-log" 4 .IX Item "--log" type: string .Sp Print all output to this file when daemonized. .IP "\-\-master\-server\-id" 4 .IX Item "--master-server-id" type: string .Sp Calculate delay from this master server \s-1ID\s0 for \*(L"\-\-monitor\*(R" or \*(L"\-\-check\*(R". If not given, pt-heartbeat attempts to connect to the server's master and determine its server id. .IP "\-\-monitor" 4 .IX Item "--monitor" Monitor slave delay continuously. .Sp Specifies that pt-heartbeat should check the slave's delay every second and report to \s-1STDOUT\s0 (or if \*(L"\-\-file\*(R" is given, to the file instead). The output is the current delay followed by moving averages over the timeframe given in \&\*(L"\-\-frames\*(R". For example, .Sp .Vb 1 \& 5s [ 0.25s, 0.05s, 0.02s ] .Ve .IP "\-\-password" 4 .IX Item "--password" short form: \-p; type: string .Sp Password to use when connecting. .IP "\-\-pid" 4 .IX Item "--pid" type: string .Sp Create the given \s-1PID\s0 file when daemonized. The file contains the process \s-1ID\s0 of the daemonized instance. The \s-1PID\s0 file is removed when the daemonized instance exits. The program checks for the existence of the \s-1PID\s0 file when starting; if it exists and the process with the matching \s-1PID\s0 exists, the program exits. .IP "\-\-port" 4 .IX Item "--port" short form: \-P; type: int .Sp Port number to use for connection. .IP "\-\-print\-master\-server\-id" 4 .IX Item "--print-master-server-id" Print the auto-detected or given \*(L"\-\-master\-server\-id\*(R". If \*(L"\-\-check\*(R" or \*(L"\-\-monitor\*(R" is specified, specifying this option will print the auto-detected or given \*(L"\-\-master\-server\-id\*(R" at the end of each line. .IP "\-\-recurse" 4 .IX Item "--recurse" type: int .Sp Check slaves recursively to this depth in \*(L"\-\-check\*(R" mode. .Sp 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. .Sp This currently works only with MySQL. See \*(L"\-\-recursion\-method\*(R". .IP "\-\-recursion\-method" 4 .IX Item "--recursion-method" type: string .Sp Preferred recursion method used to find slaves. .Sp Possible methods are: .Sp .Vb 5 \& METHOD USES \& =========== ================== \& processlist SHOW PROCESSLIST \& hosts SHOW SLAVE HOSTS \& none Do not find slaves .Ve .Sp The processlist method is preferred because \s-1SHOW\s0 \s-1SLAVE\s0 \s-1HOSTS\s0 is not reliable. However, the hosts method is required if the server uses a non-standard port (not 3306). Usually pt-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. .IP "\-\-replace" 4 .IX Item "--replace" Use \f(CW\*(C`REPLACE\*(C'\fR instead of \f(CW\*(C`UPDATE\*(C'\fR for \-\-update. .Sp When running in \*(L"\-\-update\*(R" mode, use \f(CW\*(C`REPLACE\*(C'\fR instead of \f(CW\*(C`UPDATE\*(C'\fR to set the heartbeat table's timestamp. The \f(CW\*(C`REPLACE\*(C'\fR statement is a MySQL extension to \s-1SQL\s0. 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. .IP "\-\-run\-time" 4 .IX Item "--run-time" type: time .Sp Time to run before exiting. .IP "\-\-sentinel" 4 .IX Item "--sentinel" type: string; default: /tmp/pt\-heartbeat\-sentinel .Sp Exit if this file exists. .IP "\-\-set\-vars" 4 .IX Item "--set-vars" type: string; default: wait_timeout=10000 .Sp Set these MySQL variables. Immediately after connecting to MySQL, this string will be appended to \s-1SET\s0 and executed. .IP "\-\-skew" 4 .IX Item "--skew" type: float; default: 0.5 .Sp How long to delay checks. .Sp 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 \f(CW\*(C`PTDEBUG\*(C'\fR environment variable to see the effect this has. .IP "\-\-socket" 4 .IX Item "--socket" short form: \-S; type: string .Sp Socket file to use for connection. .IP "\-\-stop" 4 .IX Item "--stop" Stop running instances by creating the sentinel file. .Sp This should have the effect of stopping all running instances which are watching the same sentinel file. If none of \&\*(L"\-\-update\*(R", \*(L"\-\-monitor\*(R" or \*(L"\-\-check\*(R" is specified, \f(CW\*(C`pt\-heartbeat\*(C'\fR will exit after creating the file. If one of these is specified, \&\f(CW\*(C`pt\-heartbeat\*(C'\fR will wait the interval given by \*(L"\-\-interval\*(R", then remove the file and continue working. .Sp 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 \f(CW\*(C`pt\-heartbeat\*(C'\fR 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 \&\f(CW\*(C`crontab\*(C'\fR line like this: .Sp .Vb 2 \& 0 * * * * pt\-heartbeat \-\-update \-D test \-\-stop \e \& \-\-sentinel /tmp/pt\-heartbeat\-hourly .Ve .Sp The non-default \*(L"\-\-sentinel\*(R" will make sure the hourly \f(CW\*(C`cron\*(C'\fR job stops only instances previously started with the same options (that is, from the same \f(CW\*(C`cron\*(C'\fR job). .Sp See also \*(L"\-\-sentinel\*(R". .IP "\-\-table" 4 .IX Item "--table" type: string; default: heartbeat .Sp The table to use for the heartbeat. .Sp Don't specify database.table; use \*(L"\-\-database\*(R" to specify the database. .Sp See \*(L"\-\-create\-table\*(R". .IP "\-\-update" 4 .IX Item "--update" Update a master's heartbeat. .IP "\-\-user" 4 .IX Item "--user" short form: \-u; type: string .Sp User for login if not current user. .IP "\-\-version" 4 .IX Item "--version" Show version and exit. .SH "DSN OPTIONS" .IX Header "DSN OPTIONS" These \s-1DSN\s0 options are used to create a \s-1DSN\s0. Each option is given like \&\f(CW\*(C`option=value\*(C'\fR. The options are case-sensitive, so P and p are not the same option. There cannot be whitespace before or after the \f(CW\*(C`=\*(C'\fR and if the value contains whitespace it must be quoted. \s-1DSN\s0 options are comma-separated. See the percona-toolkit manpage for full details. .IP "\(bu" 4 A .Sp dsn: charset; copy: yes .Sp Default character set. .IP "\(bu" 4 D .Sp dsn: database; copy: yes .Sp Default database. .IP "\(bu" 4 F .Sp dsn: mysql_read_default_file; copy: yes .Sp Only read default options from the given file .IP "\(bu" 4 h .Sp dsn: host; copy: yes .Sp Connect to host. .IP "\(bu" 4 p .Sp dsn: password; copy: yes .Sp Password to use when connecting. .IP "\(bu" 4 P .Sp dsn: port; copy: yes .Sp Port number to use for connection. .IP "\(bu" 4 S .Sp dsn: mysql_socket; copy: yes .Sp Socket file to use for connection. .IP "\(bu" 4 u .Sp dsn: user; copy: yes .Sp User for login if not current user. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" The environment variable \f(CW\*(C`PTDEBUG\*(C'\fR enables verbose debugging output to \s-1STDERR\s0. To enable debugging and capture all output to a file, run the tool like: .PP .Vb 1 \& PTDEBUG=1 pt\-heartbeat ... > FILE 2>&1 .Ve .PP Be careful: debugging output is voluminous and can generate several megabytes of output. .SH "SYSTEM REQUIREMENTS" .IX Header "SYSTEM REQUIREMENTS" You need Perl, \s-1DBI\s0, DBD::mysql, and some core packages that ought to be installed in any reasonably new version of Perl. .SH "BUGS" .IX Header "BUGS" For a list of known bugs, see http://www.percona.com/bugs/pt\-heartbeat . .PP Please report bugs at https://bugs.launchpad.net/percona\-toolkit . Include the following information in your bug report: .IP "\(bu" 4 Complete command-line used to run the tool .IP "\(bu" 4 Tool \*(L"\-\-version\*(R" .IP "\(bu" 4 MySQL version of all servers involved .IP "\(bu" 4 Output from the tool including \s-1STDERR\s0 .IP "\(bu" 4 Input files (log/dump/config files, etc.) .PP If possible, include debugging output by running the tool with \f(CW\*(C`PTDEBUG\*(C'\fR; see \*(L"\s-1ENVIRONMENT\s0\*(R". .SH "DOWNLOADING" .IX Header "DOWNLOADING" Visit http://www.percona.com/software/percona\-toolkit/ to download the latest release of Percona Toolkit. Or, get the latest release from the command line: .PP .Vb 1 \& wget percona.com/get/percona\-toolkit.tar.gz \& \& wget percona.com/get/percona\-toolkit.rpm \& \& wget percona.com/get/percona\-toolkit.deb .Ve .PP You can also get individual tools from the latest release: .PP .Vb 1 \& wget percona.com/get/TOOL .Ve .PP Replace \f(CW\*(C`TOOL\*(C'\fR with the name of any tool. .SH "AUTHORS" .IX Header "AUTHORS" Proven Scaling \s-1LLC\s0, SixApart Ltd, Baron Schwartz, and Daniel Nichter .SH "ABOUT PERCONA TOOLKIT" .IX Header "ABOUT PERCONA TOOLKIT" This tool is part of Percona Toolkit, a collection of advanced command-line tools developed by Percona for MySQL support and consulting. Percona Toolkit was forked from two projects in June, 2011: Maatkit and Aspersa. Those projects were created by Baron Schwartz and developed primarily by him and Daniel Nichter, both of whom are employed by Percona. Visit for more software developed by Percona. .SH "COPYRIGHT, LICENSE, AND WARRANTY" .IX Header "COPYRIGHT, LICENSE, AND WARRANTY" This program is copyright 2006 Proven Scaling \s-1LLC\s0 and Six Apart Ltd, 2007\-2012 Percona Inc. Feedback and improvements are welcome. .PP Feedback and improvements are welcome. .PP \&\s-1THIS\s0 \s-1PROGRAM\s0 \s-1IS\s0 \s-1PROVIDED\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1AND\s0 \s-1WITHOUT\s0 \s-1ANY\s0 \s-1EXPRESS\s0 \s-1OR\s0 \s-1IMPLIED\s0 \&\s-1WARRANTIES\s0, \s-1INCLUDING\s0, \s-1WITHOUT\s0 \s-1LIMITATION\s0, \s-1THE\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0 \&\s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. .PP This program is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation, version 2; \s-1OR\s0 the Perl Artistic License. On \s-1UNIX\s0 and similar systems, you can issue `man perlgpl' or `man perlartistic' to read these licenses. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, \s-1MA\s0 02111\-1307 \s-1USA\s0. .SH "VERSION" .IX Header "VERSION" pt-heartbeat 2.1.2