MySQL Bugs: #54763: replication heartbeat is poorly documented

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

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.

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.

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

I did not see this bug report before - I reported BUG#57847 about the same issue.