Bug #54763 replication heartbeat is poorly documented
Submitted: 24 Jun 2010 7:27 Modified: 28 Sep 2010 14:14
Reporter: Giuseppe Maxia Email Updates:
Status: Not a Bug Impact on me:
None 
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:5.5,5.1 OS:Any
Assigned to: Jon Stephens CPU Architecture:Any
Tags: Docs, heartbeat, replication

[24 Jun 2010 7:27] Giuseppe Maxia
Description:
MySQL 5.5 introduces replication heartbeat
http://forge.mysql.com/worklog/task.php?id=342

The feature has even been backported to 5.1, since it fixes two important bugs.
However, it's difficult to find proper documentation for it.
A search for "heartbeat" doesn't return anything relevant.

The only mention of the feature is in the "CHANGE MASTER TO" syntax page, where it says what the user can do to set the feature. It doesn't say what slave and master do in response and what the user should expect when this feature is enabled.

How to repeat:
Search the manual for "replication heartbeat" or "heartbeat".

Suggested fix:
Add a "replication heartbeat" section that explains the feature from the user's standpoint, explaining what happens without and with the feature enabled. The session should suggest what a sensible interval for master_heartbeat_period should be and what the side effects could be if the value is to high or too low.
[24 Jun 2010 8:51] Andrei Elkin
5.1 docs indeed refer to the feature.
It's done mostly on NDB pages which warns explicitly

  `The next two options (MASTER_BIND and MASTER_HEARTBEAT_PERIOD) are available  
   in MySQL Cluster NDB 6.3 and later,
   but are not supported in mainline MySQL 5.1'

but at the same time few items  penetrated 
the main docs section Table 5.4. Status Variable p.454 Slave_heartbeat_period, Slave_received_heartbeats.

I suggest to search for all references of `heartbeat' to make sure the main docs refer to heartbeat on in the context of the Linux heartbeat.
[28 Sep 2010 14:14] Jon Stephens
As has been pointed out, this is supported by Cluster and 5.5+ (for which it is documented), and not in mainline 5.1 (which is also documented).
[1 Nov 2010 23:35] Lenz Grimmer
I did not see this bug report before - I reported BUG#57847 about the same issue.