fix(mysql-innodb-log-waits): stop alerting on write log efficiency

Per the MariaDB InnoDB source, only Innodb_log_waits (log_sys.waits,
incremented on the WRITE_BACKOFF path; srv0mon.cc labels it "Number of
log waits due to small log buffer") signals a too-small log buffer. The
write log efficiency ratio Innodb_log_writes / Innodb_log_write_requests
reflects group commit / innodb_flush_log_at_trx_commit batching, not
buffer capacity, so raising innodb_log_buffer_size cannot improve it.

MySQLTuner alerts and recommends a bigger buffer when that ratio drops
below 90%; this plugin now deviates deliberately and treats write log
efficiency as informational only, alerting solely on log waits. The
deviation is documented in the source, DESCRIPTION and README. The
Director basket is regenerated via build-basket --auto.

Author: markuslf

CHANGELOG.md

@@ -35,6 +35,7 @@ Monitoring Plugins:
 * disk-io: per-disk performance data now reports read/write throughput per second and disk busy percentage as ready-to-graph values instead of raw cumulative counters; re-import the disk-io Grafana dashboard after updating ([#320](https://github.com/Linuxfabrik/monitoring-plugins/issues/320))
 * disk-usage: mountpoints are now filtered with `--match` and `--ignore`, consistent with the other plugins; the previous `--include-pattern`/`--include-regex`/`--exclude-pattern`/`--exclude-regex` options keep working unchanged
 * docker-stats, podman-stats: containers can now be selected or excluded by name with `--match` / `--ignore`, consistent with the docker-container/podman-container checks, and `--no-match-severity` sets the state when nothing matches
+* mysql-innodb-log-waits: no longer warns on a low InnoDB write log efficiency, which does not actually indicate an undersized log buffer and cannot be improved by raising `innodb_log_buffer_size`; the check now alerts only on real InnoDB log waits, so the buffer-size recommendation appears only when it will help
 * mysql-logfile: documents that `--ignore-pattern`/`--ignore-regex` match against the lowercased log line, and shows how to silence the harmless idle-connection-timeout warning (server closing an idle connection after `wait_timeout`) without hiding real connection errors
 * podman-info, podman-stats: gained `--user` to report on a specific rootless user's Podman. Running these checks as root only sees root's own containers, so use `--user` for rootless setups (running via sudo does not cover other users)
 * snmp: `--device` now also accepts an absolute path, so the OID definition CSV can be stored outside the plugin directory ([#1308](https://github.com/Linuxfabrik/monitoring-plugins/issues/1308))

check-plugins/mysql-innodb-log-waits/README.md

@@ -3,23 +3,27 @@
 
 ## Overview
 
-Checks two related InnoDB log buffer health metrics in MySQL/MariaDB:
+Checks InnoDB redo log buffer health in MySQL/MariaDB:
 
-1. **Log waits** (`Innodb_log_waits` / `Innodb_log_writes`) - how often InnoDB had to wait for log writes to be flushed because the log buffer was full. Anything above 0% indicates that `innodb_log_buffer_size` is too small for the write workload.
-2. **Write log efficiency** (`(Innodb_log_write_requests - Innodb_log_writes) / Innodb_log_write_requests * 100`) - how many log write requests were absorbed by the buffer without needing a physical disk write. Below 90% indicates `innodb_log_buffer_size` is too small for the write workload.
+1. **Log waits** (`Innodb_log_waits` / `Innodb_log_writes`) - how often InnoDB had to wait because the in-memory log buffer was full before its contents could be flushed to disk. Per the MariaDB InnoDB source this counter is the authoritative signal for an undersized log buffer ("Number of log waits due to small log buffer"). Anything above 0 means `innodb_log_buffer_size` was too small for the write workload at some point. This is the only metric the plugin alerts on.
+2. **Write log efficiency** (`(Innodb_log_write_requests - Innodb_log_writes) / Innodb_log_write_requests * 100`) - the share of in-memory log appends that were batched into a shared physical write. This ratio is governed by group commit and `innodb_flush_log_at_trx_commit`, not by buffer size, so the plugin reports it for trending only. It never alerts and never recommends resizing the buffer.
+
+**Deliberate deviation from MySQLTuner:**
+
+The check logic is derived from MySQLTuner, which alerts and recommends increasing `innodb_log_buffer_size` whenever write log efficiency drops below 90%. The MariaDB InnoDB source does not support that link: only `Innodb_log_waits` reflects a too-small buffer, while the write efficiency ratio reflects commit/flush batching. This plugin therefore treats write log efficiency as informational only and alerts solely on log waits.
 
 **Important Notes:**
 
 * See [additional notes for all mysql monitoring plugins](https://linuxfabrik.github.io/monitoring-plugins/plugins-mysql/)
 * If the InnoDB engine is not available or is disabled, the plugin reports OK with an info message instead of UNKNOWN
-* The Write Log efficiency check is silently skipped on MySQL versions that do not expose `Innodb_log_write_requests` (very old MySQL pre-5.0)
-* When `Innodb_log_writes > Innodb_log_write_requests` (a physically impossible state that can briefly appear during counter resets), the plugin emits an info note instead of alerting
+* The Write Log efficiency line is silently skipped on MySQL versions that do not expose `Innodb_log_write_requests` (very old MySQL pre-5.0)
+* When `Innodb_log_writes > Innodb_log_write_requests` (a physically impossible state that can briefly appear during counter resets), the plugin emits an info note instead of a value
 
 **Data Collection:**
 
 * Queries `SHOW GLOBAL VARIABLES` for `innodb_log_buffer_size`
 * Queries `SHOW GLOBAL STATUS` for `Innodb_log_waits`, `Innodb_log_writes` and `Innodb_log_write_requests`
-* Logic is taken from [MySQLTuner](https://github.com/major/MySQLTuner-perl):mysql_innodb() (sections "InnoDB Log Waits" and "InnoDB Write Log efficiency") and has been verified in sync with MySQLTuner
+* Logic is derived from [MySQLTuner](https://github.com/major/MySQLTuner-perl):mysql_innodb() (sections "InnoDB Log Waits" and "InnoDB Write Log efficiency"), with the deliberate deviation on write log efficiency described above
 
 
 ## Fact Sheet
@@ -43,15 +47,24 @@ usage: mysql-innodb-log-waits [-h] [-V] [--always-ok]
                               [--defaults-group DEFAULTS_GROUP]
                               [--timeout TIMEOUT]
 
-Checks two related InnoDB log buffer metrics in MySQL/MariaDB: 1. **Log
-waits** (`Innodb_log_waits` / `Innodb_log_writes`) - how often InnoDB had to
-wait for log writes to be flushed because the log buffer was full. Anything
-above 0% indicates that `innodb_log_buffer_size` is too small for the write
-workload. 2. **Write log efficiency** ((`Innodb_log_write_requests` -
-`Innodb_log_writes`) / `Innodb_log_write_requests` * 100) - how many log write
-requests were absorbed by the buffer without needing a physical disk write.
-Below 90% indicates `innodb_log_buffer_size` is too small for the write
-workload. Alerts on either condition.
+Checks InnoDB redo log buffer health in MySQL/MariaDB. Primary check - **Log
+waits** (`Innodb_log_waits` / `Innodb_log_writes`): how often InnoDB had to
+wait because the in-memory log buffer was full before its contents could be
+flushed to disk. Per the MariaDB InnoDB source this counter is the
+authoritative signal for an undersized log buffer ("Number of log waits due to
+small log buffer"). Any value above 0 means `innodb_log_buffer_size` was too
+small for the write workload at some point, so the plugin alerts and
+recommends a larger buffer. Secondary informational metric - **Write log
+efficiency** ((`Innodb_log_write_requests` - `Innodb_log_writes`) /
+`Innodb_log_write_requests` * 100): the share of in-memory log appends that
+were batched into a shared physical write. This ratio is governed by group
+commit and `innodb_flush_log_at_trx_commit`, not by buffer size, so the plugin
+reports it for trending but never alerts on it and never recommends resizing
+the buffer based on it. Deliberate deviation from MySQLTuner: MySQLTuner
+alerts and recommends increasing `innodb_log_buffer_size` whenever write log
+efficiency drops below 90%. The MariaDB InnoDB source does not support that
+link, so this plugin treats write log efficiency as informational only and
+alerts solely on log waits.
 
 options:
   -h, --help            show this help message and exit
@@ -80,23 +93,26 @@ Output:
 ```text
 InnoDB log waits: 0.0% (0.0 waits / 867.6K writes).
 
-InnoDB Write Log efficiency: 95.6% (12.5M log buffer hits / 13.1M total).
+InnoDB Write Log efficiency: 95.6% (12.5M batched / 13.1M log write requests).
 ```
 
-When the buffer is undersized:
+When the buffer is undersized (only log waits trigger a WARNING; write log efficiency stays informational):
 
 ```text
-InnoDB log waits: 0.05% (450.0 waits / 867.6K writes) [WARNING]. Set `innodb_log_buffer_size` > 16.0MiB.
+InnoDB log waits: 0.05% (450.0 waits / 867.6K writes) [WARNING].
+
+InnoDB Write Log efficiency: 82.3% (5.2M batched / 6.3M log write requests).
 
-InnoDB Write Log efficiency: 82.3% (5.2M log buffer hits / 6.3M total) [WARNING]. Set `innodb_log_buffer_size` > 16.0MiB.
+Recommendations:
+* Set `innodb_log_buffer_size` > 16.0MiB
 ```
 
 
 ## States
 
 * WARN if `Innodb_log_waits > 0` (any wait at all means the buffer was too small at some point).
-* WARN if InnoDB Write Log efficiency is below 90%.
 * OK if the InnoDB engine is not available or is disabled.
+* Write Log efficiency is informational only and never changes the state.
 * `--always-ok` suppresses all alerts and always returns OK.
 
 

check-plugins/mysql-innodb-log-waits/icingaweb2-module-director/mysql-innodb-log-waits.json

@@ -80,7 +80,7 @@
                 "tpl-service-generic"
             ],
             "max_check_attempts": 5,
-            "notes": "Checks two related InnoDB log buffer metrics in MySQL/MariaDB: 1. **Log waits** (`Innodb_log_waits` / `Innodb_log_writes`) - how often InnoDB had to wait for log writes to be flushed because the log buffer was full. Anything above 0% indicates that `innodb_log_buffer_size` is too small for the write workload. 2. **Write log efficiency** ((`Innodb_log_write_requests` - `Innodb_log_writes`) / `Innodb_log_write_requests` * 100) - how many log write requests were absorbed by the buffer without needing a physical disk write. Below 90% indicates `innodb_log_buffer_size` is too small for the write workload. Alerts on either condition.",
+            "notes": "Checks InnoDB redo log buffer health in MySQL/MariaDB. Primary check - **Log waits** (`Innodb_log_waits` / `Innodb_log_writes`): how often InnoDB had to wait because the in-memory log buffer was full before its contents could be flushed to disk. Per the MariaDB InnoDB source this counter is the authoritative signal for an undersized log buffer (\"Number of log waits due to small log buffer\"). Any value above 0 means `innodb_log_buffer_size` was too small for the write workload at some point, so the plugin alerts and recommends a larger buffer. Secondary informational metric - **Write log efficiency** ((`Innodb_log_write_requests` - `Innodb_log_writes`) / `Innodb_log_write_requests` * 100): the share of in-memory log appends that were batched into a shared physical write. This ratio is governed by group commit and `innodb_flush_log_at_trx_commit`, not by buffer size, so the plugin reports it for trending but never alerts on it and never recommends resizing the buffer based on it. Deliberate deviation from MySQLTuner: MySQLTuner alerts and recommends increasing `innodb_log_buffer_size` whenever write log efficiency drops below 90%. The MariaDB InnoDB source does not support that link, so this plugin treats write log efficiency as informational only and alerts solely on log waits.",
             "notes_url": "https://linuxfabrik.github.io/monitoring-plugins/check-plugins/mysql-innodb-log-waits/",
             "object_name": "tpl-service-mysql-innodb-log-waits",
             "object_type": "template",

check-plugins/mysql-innodb-log-waits/mysql-innodb-log-waits

@@ -21,17 +21,27 @@ import lib.human
 from lib.globals import STATE_OK, STATE_UNKNOWN, STATE_WARN
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026060201'
-
-DESCRIPTION = """Checks two related InnoDB log buffer metrics in MySQL/MariaDB:
-1. **Log waits** (`Innodb_log_waits` / `Innodb_log_writes`) - how often InnoDB had to wait for
-   log writes to be flushed because the log buffer was full. Anything above 0% indicates that
-   `innodb_log_buffer_size` is too small for the write workload.
-2. **Write log efficiency** ((`Innodb_log_write_requests` - `Innodb_log_writes`) /
-   `Innodb_log_write_requests` * 100) - how many log write requests were absorbed by the buffer
-   without needing a physical disk write. Below 90% indicates `innodb_log_buffer_size` is too
-   small for the write workload.
-Alerts on either condition."""
+__version__ = '2026070101'
+
+DESCRIPTION = """Checks InnoDB redo log buffer health in MySQL/MariaDB.
+
+Primary check - **Log waits** (`Innodb_log_waits` / `Innodb_log_writes`): how often InnoDB had to
+wait because the in-memory log buffer was full before its contents could be flushed to disk. Per
+the MariaDB InnoDB source this counter is the authoritative signal for an undersized log buffer
+("Number of log waits due to small log buffer"). Any value above 0 means `innodb_log_buffer_size`
+was too small for the write workload at some point, so the plugin alerts and recommends a larger
+buffer.
+
+Secondary informational metric - **Write log efficiency** ((`Innodb_log_write_requests` -
+`Innodb_log_writes`) / `Innodb_log_write_requests` * 100): the share of in-memory log appends that
+were batched into a shared physical write. This ratio is governed by group commit and
+`innodb_flush_log_at_trx_commit`, not by buffer size, so the plugin reports it for trending but
+never alerts on it and never recommends resizing the buffer based on it.
+
+Deliberate deviation from MySQLTuner: MySQLTuner alerts and recommends increasing
+`innodb_log_buffer_size` whenever write log efficiency drops below 90%. The MariaDB InnoDB source
+does not support that link, so this plugin treats write log efficiency as informational only and
+alerts solely on log waits."""
 
 DEFAULT_DEFAULTS_FILE = '/var/spool/icinga2/.my.cnf'
 DEFAULT_DEFAULTS_GROUP = 'client'
@@ -112,10 +122,20 @@ def get_status(conn):
 def main():
     """The main function. This is where the magic happens."""
 
-    # logic taken from mysqltuner.pl:mysql_innodb(), sections "InnoDB Write Log
-    # efficiency" and "InnoDB Log Waits", verified in sync with MySQLTuner
-    # (the < 90% write-efficiency threshold and the "any waits at all" log-wait
-    # threshold are unchanged upstream since the original port).
+    # Logic derived from mysqltuner.pl:mysql_innodb(), sections "InnoDB Write Log
+    # efficiency" and "InnoDB Log Waits". Deliberate deviation from MySQLTuner:
+    # only `Innodb_log_waits > 0` alerts and recommends a larger
+    # `innodb_log_buffer_size`. Per the MariaDB InnoDB source, `Innodb_log_waits`
+    # (`log_sys.waits`, incremented only on the WRITE_BACKOFF path when an append
+    # must wait for a full buffer) is the sole counter that signals a too-small
+    # log buffer - srv0mon.cc labels it "Number of log waits due to small log
+    # buffer". The Write Log efficiency ratio Innodb_log_writes /
+    # Innodb_log_write_requests instead measures how many in-memory log appends
+    # were batched into a shared physical write (group commit /
+    # `innodb_flush_log_at_trx_commit` behavior), which is unrelated to buffer
+    # capacity. MySQLTuner alerts and recommends a bigger buffer when that ratio
+    # drops below 90%; since the source does not support that, we emit it as an
+    # informational metric only.
 
     # parse the command line
     try:
@@ -188,10 +208,13 @@ def main():
     else:
         sections.append(f'{log_waits_msg}.')
 
-    # 2. InnoDB Write Log efficiency: only computable when the server exposes
-    #    `Innodb_log_write_requests` (older MySQL did not). mysqltuner emits a
-    #    "metrics not reliable" infoprint when `writes > write_requests` (which
-    #    cannot happen physically); we mirror that as an info line.
+    # 2. InnoDB Write Log efficiency: informational only. Unlike MySQLTuner (see
+    #    the note at the top of main()) this never alerts and never recommends a
+    #    larger buffer, because the ratio reflects group commit /
+    #    `innodb_flush_log_at_trx_commit` batching, not buffer capacity. Only
+    #    computable when the server exposes `Innodb_log_write_requests` (older
+    #    MySQL did not). `writes > write_requests` cannot happen physically and
+    #    briefly appears only during counter resets, so it is reported as info.
     if log_write_requests is not None:
         if log_write_requests == 0:
             sections.append(
@@ -207,25 +230,12 @@ def main():
             pct_write_eff = round(
                 (log_write_requests - log_writes) / log_write_requests * 100, 1
             )
-            absorbed = log_write_requests - log_writes
-            eff_msg = (
+            batched = log_write_requests - log_writes
+            sections.append(
                 f'InnoDB Write Log efficiency: {pct_write_eff}%'
-                f' ({lib.human.number2human(absorbed)} log buffer hits /'
-                f' {lib.human.number2human(log_write_requests)} total)'
+                f' ({lib.human.number2human(batched)} batched /'
+                f' {lib.human.number2human(log_write_requests)} log write requests).'
             )
-            if pct_write_eff < 90:
-                state = lib.base.get_worst(state, STATE_WARN)
-                sections.append(
-                    f'{eff_msg}{lib.base.state2str(STATE_WARN, prefix=" ")}.'
-                )
-                rec = (
-                    f'Set `innodb_log_buffer_size` >'
-                    f' {lib.human.bytes2human(log_buffer_size)}'
-                )
-                if rec not in recommendations:
-                    recommendations.append(rec)
-            else:
-                sections.append(f'{eff_msg}.')
 
     # build the message
     if recommendations: