DOC: management: document 'clear counters server'

Add a section for the new 'clear counters server <backend>/<server>
[force]' CLI command in doc/management.txt, alongside 'clear counters'
and 'clear counters all'.

The entry documents the admin-only permission level (it clears
accumulated counters, like 'clear counters all') and the fact that both
accumulated counters and max values are reset, along with the clearable
module-registered extra counters, while the server's runtime state
(address, weight, admin state) and health checks are left untouched. It
describes the optional 'force' argument required to clear counters
stored in a shared-memory stats file, and calls out the Kubernetes
slot-recycle use case that motivated the command (per-entity
attribution after 'set server <b>/<s> name').

diff --git a/doc/management.txt b/doc/management.txt
index 6cd2f42706a4541080f05def9eaac434264bd5e6..7077ad69b61d9cc7f926a9df2d48df104278d4c5 100644 (file)
--- a/doc/management.txt
+++ b/doc/management.txt
@@ -1922,6 +1922,30 @@ clear counters all
   server. This has the same effect as restarting. This command is restricted
   and can only be issued on sockets configured for level "admin".
 
+clear counters server <backend>/<server> [force]
+  Reset the statistics counters of a single server. This command is useful when
+  a server slot is being reused to represent a different logical entity (e.g.
+  a different Kubernetes pod occupying the same slot after a rename via
+  "set server <b>/<s> name") and per-entity counter attribution is required.
+  It behaves like "clear counters all" but scoped to one server rather than the
+  whole process.
+
+  The reset covers both accumulated counters (bytes, sessions, requests,
+  errors, response codes) and max values, as well as the extra counters
+  registered by modules (e.g. mux stats) for that server. As for the plain
+  "clear counters", only clearable modules are reset. It does not affect the
+  server's runtime state (address, weight, admin state) or health checks.
+
+  When the server's counters are stored in a shared-memory stats file (see
+  "shm-stats-file"), clearing them breaks the monotonicity that monitoring
+  tools consuming the shared stats rely on, and the reset is visible to every
+  process attached to the same object. For this reason the command refuses to
+  clear such a server unless the "force" keyword is appended.
+
+  Because it clears accumulated counters, this command is restricted and can
+  only be issued on sockets configured for level "admin", like "clear counters
+  all".
+
 clear acl [@<ver>] <acl>
   Remove all entries from the acl <acl>. <acl> is the #<id> or the <name>
   returned by "show acl". Note that if the reference <acl> is a name and is