Bug #97398 Wrong documentation for innodb_max_purge_lag.
Submitted: 28 Oct 2019 13:57 Modified: 5 Nov 2019 15:49
Reporter: Jean-François Gagné Email Updates:
Status: Closed Impact on me:
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:5.7 OS:Any
Assigned to: CPU Architecture:Any

[28 Oct 2019 13:57] Jean-François Gagné

it looks like there is an error in the 5.7 reference manual for innodb_max_purge_lag.  In [1], I can read:

Specifies the maximum delay in microseconds for the delay imposed when the innodb_max_purge_lag threshold is exceeded. The specified innodb_max_purge_lag_delay value is an upper limit on the delay period calculated by the innodb_max_purge_lag formula.

[1]: https://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_max_purge_lag

But this looks like a bad edit as it duplicates a lot of text from innodb_max_purge_lag_delay ([2]).  In the 5.6 and 8.0 documentations ([3] and [4]), I can read below which makes more sense:

Defines the desired maximum purge lag. If this value is exceeded, a delay is imposed on INSERT, UPDATE, and DELETE operations to allow time for purge to catch up. The default value is 0, which means there is no maximum purge lag and no delay.

[2]: https://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_max_purge_lag...

[3]: https://dev.mysql.com/doc/refman/5.6/en/innodb-parameters.html#sysvar_innodb_max_purge_lag

[4]: https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_max_purge_lag

At the same time, please review the 5.7 documentation for innodb_max_purge_lag_delay [5] as there is a reference to "Optimizing InnoDB Disk I/O” which is not present in 5.6 and 8.0 documentation (this also looks like a bad edit).

[5]: https://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_max_purge_lag

Finally, the 5.6 and 8.0 documentation for innodb_max_purge_lag_delay ([6] and [7]) reference a "innodb_max_purge_lag formula" but there are no formula in the innodb_max_purge_lag documentation ([3] and [4] above).  There is a formula in the "Purge Configuration" documentation the is reference in the next sentence in the documentation, so this formula should either be copied in the documentation of innodb_max_purge_lag of the reference to a formula removed/edited.

[6]: https://dev.mysql.com/doc/refman/5.6/en/innodb-parameters.html#sysvar_innodb_max_purge_lag

[7]: https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_max_purge_lag

Many thanks for looking into that, JFG

How to repeat:
Documentation bug fully explained in description.

Suggested fix:
Fix the documentation.
[28 Oct 2019 15:03] MySQL Verification Team
Thank you for the bug report.
[5 Nov 2019 15:49] Daniel Price
Posted by developer:
The inconsistencies in the referenced documentation have been addressed. Changes should appear online soon.

Thank you for the bug report.