[PATCH net-next v3 5/5] docs: netconsole: document rate limit feature

[Breno Leitao]

Describe the per-target token bucket and the two configfs files that
drive it: ratelimit_interval_ms and ratelimit_burst.

Spell out the two properties that are not obvious from the file names.
The limit is accounted per message rather than per packet, so a message
split into several ncfrag packets is never truncated by the bucket
running dry halfway through.

List both files in the target parameter table too, and qualify the rule
underneath it. Only a disabled target can have its parameters updated,
these two aside.

Note in the message ID section that a message the bucket discards never
reaches the counter, so those drops leave no gap in the IDs.

Signed-off-by: Breno Leitao <leitao@xxxxxxxxxx>
---
 Documentation/networking/netconsole.rst | 71 ++++++++++++++++++++++++++-------
 1 file changed, 57 insertions(+), 14 deletions(-)

diff --git a/Documentation/networking/netconsole.rst b/Documentation/networking/netconsole.rst
index 4ab5d7b05cf102..9fe4888fe136b3 100644
--- a/Documentation/networking/netconsole.rst
+++ b/Documentation/networking/netconsole.rst
@@ -127,23 +127,26 @@ To remove a target::
 
 The interface exposes these parameters of a netconsole target to userspace:
 
-	=============== =================================       ============
-	enabled		Is this target currently enabled?	(read-write)
-	extended	Extended mode enabled			(read-write)
-	release		Prepend kernel release to message	(read-write)
-	dev_name	Local network interface name		(read-write)
-	local_port	Source UDP port to use			(read-write)
-	remote_port	Remote agent's UDP port			(read-write)
-	local_ip	Source IP address to use		(read-write)
-	remote_ip	Remote agent's IP address		(read-write)
-	local_mac	Local interface's MAC address		(read-only)
-	remote_mac	Remote agent's MAC address		(read-write)
-	transmit_errors	Number of packet send errors		(read-only)
-	=============== =================================       ============
+	===================== ================================= ============
+	enabled               Is this target currently enabled? (read-write)
+	extended              Extended mode enabled             (read-write)
+	release               Prepend kernel release to message (read-write)
+	dev_name              Local network interface name      (read-write)
+	local_port            Source UDP port to use            (read-write)
+	remote_port           Remote agent's UDP port           (read-write)
+	local_ip              Source IP address to use          (read-write)
+	remote_ip             Remote agent's IP address         (read-write)
+	local_mac             Local interface's MAC address     (read-only)
+	remote_mac            Remote agent's MAC address        (read-write)
+	transmit_errors       Number of packet send errors      (read-only)
+	ratelimit_interval_ms Rate limit interval, milliseconds (read-write)
+	ratelimit_burst       Messages allowed per interval     (read-write)
+	===================== ================================= ============
 
 The "enabled" attribute is also used to control whether the parameters of
 a target can be updated or not -- you can modify the parameters of only
-disabled targets (i.e. if "enabled" is 0).
+disabled targets (i.e. if "enabled" is 0). The two rate limit parameters
+are the exception, see `Rate limiting`_.
 
 To update a target's parameters::
 
@@ -177,6 +180,43 @@ You can modify these targets in runtime by creating the following targets::
  cat cmdline1/remote_ip
  10.0.0.3
 
+Rate limiting
+-------------
+
+Netconsole hands every console message to every enabled target, so a host that
+logs continuously can saturate the receiving agent. Each target carries a token
+bucket that drops messages once the configured rate is exceeded, controlled by
+two files in the target directory:
+
+        ===================== ================================================
+        ratelimit_interval_ms Length of the accounting interval, in
+                              milliseconds. Zero, the default, sends
+                              everything.
+        ratelimit_burst       Messages allowed per interval. Defaults to
+                              10; zero drops every message once an
+                              interval is set.
+        ===================== ================================================
+
+Unlike most target parameters, both knobs can be written while the target is
+enabled, which is when a flooding target most likely needs them. Either write
+restarts the interval with a full burst, so a new limit applies from that
+moment on.
+
+The limit is applied per message, not per packet, so a message big enough to be
+split into several `ncfrag` packets is either sent whole or not at all.
+
+Crash output bypasses the bucket. Every message is sent while a panic is in
+progress, and an oops or a BUG() turns the limit off for the rest of the boot,
+so a small burst cannot cost you part of a crash dump.
+
+A drop leaves nothing on the wire. On an extended target it shows up as a gap
+in the sequence number the header carries; a basic target has no such marker.
+
+Capping a target at 500 messages a minute::
+
+  echo 60000 > ratelimit_interval_ms
+  echo 500 > ratelimit_burst
+
 Append User Data
 ----------------
 
@@ -359,6 +399,9 @@ indicate that a message was dropped during transmission, as it may never have
 been sent via netconsole. The message ID, on the other hand, is only assigned
 to messages that are actually transmitted via netconsole.
 
+A message the target's rate limit discards is dropped before the ID is
+assigned, so those drops leave no gap in the sequence of IDs either.
+
 Example::
 
   echo "This is message #1" > /dev/kmsg

-- 
2.53.0-Meta