MINOR: debug/cli: replace "debug dev counters" with "debug counters"

"debug dev" commands are not meant to be used by end-users, and are
purposely not documented. Yet due to their usefulness in troubleshooting
sessions, users are increasingly invited by developers to use some of
them.

"debug dev counters" is one of them. Better move it to "debug counters"
and document it so that users can check them even if the output can look
cryptic at times. This, combined with DEBUG_GLITCHES, can be convenient
to observe suspcious activity. The doc however precises that the format
may change between versions and that new entries/types might appear
within a stable branch.

diff --git a/doc/management.txt b/doc/management.txt
index f716cbad851b485aaa10fc8065ee55acd9a2e9cd..5fb48074be81e0a991dffdcfd8e9c00e748a4422 100644 (file)
--- a/doc/management.txt
+++ b/doc/management.txt
@@ -1990,6 +1990,38 @@ commit ssl crl-file <crlfile>
   See also "new ssl crl-file", "set ssl crl-file", "abort ssl crl-file" and
   "add ssl crt-list".
 
+debug counters [reset|show|all|bug|chk|cnt|glt|?]*
+  List internal counters placed in the code, which may vary depending on some
+  build options. Some of them depend on DEBUG_STRICT, others on DEBUG_GLITCHES.
+  The command takes a combination of multiple arguments, some defining actions
+  and others defining filters:
+    - bug     enables listing the counters for BUG_ON() statements
+    - cnt     enables listing the counters for COUNT_IF() statements
+    - chk     enables listing the counters for CHECK_IF() statements
+    - glt     enables listing the counters for COUNT_GLITCH() statements
+    - all     enables showing counters that never triggered (value 0)
+    - reset   action: resets all specified counters
+    - show    action: shows all specified counters
+
+  By default, the action is "show" to show counters, and the listed counters
+  are all types with a non-zero value. The "show" command is implicit when no
+  other action is specified, and is only present to ease the production of
+  commands from scripts.
+
+  The output starts with an integer counter, followed by the type of the
+  counter in upper case, then its location in the code (file:line), the
+  function name, and optionally ": " followed by a description. Please note
+  that the output format might change between major versions, and new types
+  and entries might be backported to stable versions for the purpose of
+  improved debugging capabilities. Any monitoring performed on them should
+  only be done in a very lenient and permissive way, and preferably not.
+
+  Normally, end users will not use this command, but they may be invited to do
+  so by a developer trying to figure the cause of an issue, looking for CNT or
+  GLT entries. By the way, non-zero "CHK" entries are not expected to happen
+  and should be reported to developers as they might indicate some incorrect
+  assumptions in the code.
+
 debug dev <command> [args]*
   Call a developer-specific command. Only supported on a CLI connection running
   in expert mode (see "expert-mode on"). Such commands are extremely dangerous

diff --git a/src/debug.c b/src/debug.c
index ee99135439b2b493365b06334903a72b40875360..de1dfb8f942770b13c70b06ad7611024e274f584 100644 (file)
--- a/src/debug.c
+++ b/src/debug.c
@@ -2210,17 +2210,17 @@ static void debug_release_memstats(struct appctx *appctx)
 
 #if !defined(USE_OBSOLETE_LINKER)
 
-/* CLI state for "debug dev counters" */
-struct dev_cnt_ctx {
+/* CLI state for "debug counters" */
+struct deb_cnt_ctx {
        struct debug_count *start, *stop; /* begin/end of dump */
        int types;                        /* OR mask of 1<<type */
        int show_all;                     /* show all entries if non-null */
 };
 
-/* CLI parser for the "debug dev counters" command. Sets a dev_cnt_ctx shown above. */
+/* CLI parser for the "debug counters" command. Sets a deb_cnt_ctx shown above. */
 static int debug_parse_cli_counters(char **args, char *payload, struct appctx *appctx, void *private)
 {
-       struct dev_cnt_ctx *ctx = applet_reserve_svcctx(appctx, sizeof(*ctx));
+       struct deb_cnt_ctx *ctx = applet_reserve_svcctx(appctx, sizeof(*ctx));
        int action;
        int arg;
 
@@ -2228,7 +2228,7 @@ static int debug_parse_cli_counters(char **args, char *payload, struct appctx *a
                return 1;
 
        action = 0; // 0=show, 1=reset
-       for (arg = 3; *args[arg]; arg++) {
+       for (arg = 2; *args[arg]; arg++) {
                if (strcmp(args[arg], "reset") == 0) {
                        action = 1;
                        continue;
@@ -2281,7 +2281,7 @@ static int debug_parse_cli_counters(char **args, char *payload, struct appctx *a
        return 0;
 }
 
-/* CLI I/O handler for the "debug dev counters" command using a dev_cnt_ctx
+/* CLI I/O handler for the "debug counters" command using a deb_cnt_ctx
  * found in appctx->svcctx. Dumps all mem_stats structs referenced by pointers
  * located between ->start and ->stop. Dumps all entries if ->show_all != 0,
  * otherwise only non-zero calls.
@@ -2294,7 +2294,7 @@ static int debug_iohandler_counters(struct appctx *appctx)
                [DBG_COUNT_IF] = "CNT",
                [DBG_GLITCH]   = "GLT",
        };
-       struct dev_cnt_ctx *ctx = appctx->svcctx;
+       struct deb_cnt_ctx *ctx = appctx->svcctx;
        struct debug_count *ptr;
        int ret = 1;
 
@@ -2746,12 +2746,12 @@ REGISTER_PER_THREAD_INIT(feed_post_mortem_late);
 
 /* register cli keywords */
 static struct cli_kw_list cli_kws = {{ },{
+#if !defined(USE_OBSOLETE_LINKER)
+       {{ "debug", "counters", NULL },        "debug counters [?|all|bug|cnt|chk|glt]* : dump/reset rare event counters",          debug_parse_cli_counters, debug_iohandler_counters, NULL, NULL, 0 },
+#endif
        {{ "debug", "dev", "bug", NULL },      "debug dev bug                           : call BUG_ON() and crash",                 debug_parse_cli_bug,   NULL, NULL, NULL, ACCESS_EXPERT },
        {{ "debug", "dev", "check", NULL },    "debug dev check                         : call CHECK_IF() and possibly crash",      debug_parse_cli_check, NULL, NULL, NULL, ACCESS_EXPERT },
        {{ "debug", "dev", "close", NULL },    "debug dev close  <fd> [hard]            : close this file descriptor",              debug_parse_cli_close, NULL, NULL, NULL, ACCESS_EXPERT },
-#if !defined(USE_OBSOLETE_LINKER)
-       {{ "debug", "dev", "counters", NULL }, "debug dev counters [all|bug|cnt|chk|?]* : dump/reset rare event counters",          debug_parse_cli_counters, debug_iohandler_counters, NULL, NULL, 0 },
-#endif
        {{ "debug", "dev", "deadlock", NULL }, "debug dev deadlock [nbtask]             : deadlock between this number of tasks",   debug_parse_cli_deadlock, NULL, NULL, NULL, ACCESS_EXPERT },
        {{ "debug", "dev", "delay", NULL },    "debug dev delay  [ms]                   : sleep this long",                         debug_parse_cli_delay, NULL, NULL, NULL, ACCESS_EXPERT },
 #if defined(DEBUG_DEV)