MINOR: stream/cli: rework "show sess" to better consider optional arguments

The "show sess" CLI command parser is getting really annoying because
several options were added in an exclusive mode as the single possible
argument. Recently some cumulable options were added ("show-uri") but
the older ones were not yet adapted. Let's just make sure that the
various filters such as "older" and "age" now belong to the options
and leave only <id>, "all", and "help" for the first ones. The doc was
updated and it's now easier to find these options.

diff --git a/doc/management.txt b/doc/management.txt
index aa542769cccc0d9dc482126f4951d02c5bafe5c0..b4bfcf93719a1c30e36e1c1bb356f2e848461e1a 100644 (file)
--- a/doc/management.txt
+++ b/doc/management.txt
@@ -3336,30 +3336,38 @@ show sess [<options>*]
   entered; those which die in the mean time will not appear.
   For supported opitons, see below.
 
-show sess [<id> | older <age> | susp | all] [<options>*]
-  Display a lot of internal information about the matching streams. In the
-  first form, only the stream matching the specified stream identifier will
-  be shown. This identifier is the first field at the beginning of the lines in
-  the dumps of "show sess" (it corresponds to the stream pointer). In the
-  second form, only streams older than <age> (in seconds by default) will be
-  shown. Passing "susp" instead will only report entries that are considered as
-  suspicious by the developers based on criteria that may in time or vary along
-  versions. If "all" is used instead, then all streams will be dumped. Dumping
-  many streams can produce a huge output, take a lot of time and be CPU
-  intensive, so it's always better to only dump the minimum needed. Those
-  information are useless to most users but may be used by haproxy developers
-  to troubleshoot a complex bug. The output format is intentionally not
-  documented so that it can freely evolve depending on demands. This output
-  is meant to be interpreted while checking function strm_dump_to_buffer() in
-  src/stream.c to figure the exact meaning of certain fields.
-
-  It is possible to set some options to customize the dump. Here are the
-  supported options:
-
-    - show-uri: Dump the transaction URI, as captured during the request
-      analysis. It is only displayed if it was captured.
-
-    - help:     dump a more detailed help message instead
+show sess [<id> | all | help] [<options>*]
+  Display a lot of internal information about the matching streams. The command
+  knows two output formats: a short one, which is the default when not asking
+  for a specific stream identifier, and an extended one when listing designated
+  streams. The short format, used by default with "show sess", only dumps one
+  stream per line with a few info, and the stream identifier at the beginning
+  of the line in hexadecimal (it corresponds to the pointer to the stream).
+
+  In the extended form, used by "show sess <id>" or "show sess all", streams
+  are dumped with a huge amount of debugging details over multiple lines
+  (around 20 each), and still start with their identifier. The delimiter
+  between streams here is the identifier at the beginning of the line; extra
+  lines belonging to the same stream start with one or multiple spaces (the
+  stream is dumped indented). Dumping many streams can produce a huge output,
+  take a lot of time and be CPU intensive, so it's always better to only dump
+  the minimum needed. Those information are useless to most users but may be
+  used by HAProxy developers to troubleshoot a complex bug. The exact output
+  format is intentionally not documented so that it can freely evolve depending
+  on requirements, including in stable branches. This output is meant to be
+  interpreted while checking function strm_dump_to_buffer() in src/stream.c to
+  figure the exact meaning of certain fields.
+
+  The "help" argument will show the detailed usage of the command instead of
+  dumping streams.
+
+  It is possible to set some options to customize the dump or apply some
+  filters. Here are the supported options:
+    - older <age>  only display streams older than <age> seconds
+    - show-uri     dump the transaction URI, as captured during the request
+                   analysis. It is only displayed if it was captured.
+    - susp         only show streams considered as suspicious by the developers
+                   based on criteria that may in time or vary along versions.
 
 show stat [domain <resolvers|proxy>] [{<iid>|<proxy>} <type> <sid>] \
           [typed|json] [desc] [up|no-maint]

diff --git a/src/stream.c b/src/stream.c
index b489a32c3fee344cc98b60f6e72c62f66eb520b2..c7ba90d948bc6cbbfd24507cff404525b49e70a9 100644 (file)
--- a/src/stream.c
+++ b/src/stream.c
@@ -3764,25 +3764,21 @@ static int cli_parse_show_sess(char **args, char *payload, struct appctx *appctx
                ctx->target = (void *)-1; /* show all matching entries */
                cur_arg +=2;
        }
-       else if (*args[cur_arg] && strcmp(args[cur_arg], "susp") == 0) {
-               ctx->flags |= CLI_SHOWSESS_F_SUSP;
-               ctx->target = (void *)-1; /* show all matching entries */
-               cur_arg++;
-       }
        else if (*args[cur_arg] && strcmp(args[cur_arg], "all") == 0) {
                ctx->target = (void *)-1;
                cur_arg++;
        }
        else if (*args[cur_arg] && strcmp(args[cur_arg], "help") == 0) {
                chunk_printf(&trash,
-                            "Usage: show sess [<id> | older <age> | susp | all] [<options>*]\n"
+                            "Usage: show sess [<id> | all | help] [<options>*]\n"
                             "Dumps active streams (formerly called 'sessions'). Available selectors:\n"
                             "   <id>         dump only this stream identifier (0x...)\n"
-                            "   all          dump all stream in large format\n"
-                            "   older <age>  only display stream older than <age>\n"
+                            "   all          dump all matching streams in large format\n"
+                            "   help         show this message\n"
                             "   susp         report streams considered suspicious\n"
                             "Available options: \n"
                             "   show-uri     also display the transaction URI, if available\n"
+                            "   older <age>  only display streams older than <age> seconds\n"
                             "Without any argument, all streams are dumped in a shorter format.");
                return cli_err(appctx, trash.area);
        }
@@ -3797,6 +3793,9 @@ static int cli_parse_show_sess(char **args, char *payload, struct appctx *appctx
                if (*args[cur_arg] && strcmp(args[cur_arg], "show-uri") == 0) {
                        ctx->flags |= CLI_SHOWSESS_F_DUMP_URI;
                }
+               else if (*args[cur_arg] && strcmp(args[cur_arg], "susp") == 0) {
+                       ctx->flags |= CLI_SHOWSESS_F_SUSP;
+               }
                else {
                        chunk_printf(&trash, "Unsupported option '%s', try 'help' for more info.\n", args[cur_arg]);
                        return cli_err(appctx, trash.area);
@@ -4117,7 +4116,7 @@ static int cli_parse_shutdown_sessions_server(char **args, char *payload, struct
 
 /* register cli keywords */
 static struct cli_kw_list cli_kws = {{ },{
-       { { "show", "sess",  NULL },             "show sess [help|<id>|all|susp|older...] : report the list of current streams or dump this exact stream", cli_parse_show_sess, cli_io_handler_dump_sess, cli_release_show_sess },
+       { { "show", "sess",  NULL },             "show sess [help|<id>|all] [opts...]     : report the list of current streams or dump this exact stream",   cli_parse_show_sess, cli_io_handler_dump_sess, cli_release_show_sess },
        { { "shutdown", "session",  NULL },      "shutdown session [id]                   : kill a specific session",                                        cli_parse_shutdown_session, NULL, NULL },
        { { "shutdown", "sessions",  "server" }, "shutdown sessions server <bk>/<srv>     : kill sessions on a server",                                      cli_parse_shutdown_sessions_server, NULL, NULL },
        {{},}