MINOR: trace: change the "payload" level to "data" and move it

The "payload" trace level was ambigous because its initial purpose was
to be able to dump received data. But it doesn't make sense to force to
report data transfers just to be able to report state changes. For
example, all snd_buf()/rcv_buf() operations coming from the application
layer should be tagged at this level. So here we move this payload level
above the state transitions and rename it to avoid the ambiguity making
one think it's only about request/response payload. Now it clearly is
about any data transfer and is thus just below the developer level. The
help messages on the CLI and the doc were slightly reworded to help
remove this ambiguity.

diff --git a/doc/management.txt b/doc/management.txt
index 8b3f6f6138b2b007a87ca4b5b96a9028d4317239..1dd52f5c87cf8987bb6aba0ca5294ba308790048 100644 (file)
--- a/doc/management.txt
+++ b/doc/management.txt
@@ -2642,15 +2642,15 @@ trace <source> event [ [+|-|!]<name> ]
   this source will instantly be totally ignored.
 
 trace <source> level [<level>]
-  Without argument, this will list all detail levels for this source, and the
+  Without argument, this will list all trace levels for this source, and the
   current one will be indicated by a star ('*') prepended in front of it. With
-  an argument, this will change the detail level to the specified level. Detail
+  an argument, this will change the trace level to the specified level. Detail
   levels are a form of filters that are applied before reporting the events.
-  These filters are used to report a level of detail suitable for the use case.
-  For example a developer might need to know precisely where in the code an
-  HTTP header was considered invalid while the end user may not even care about
-  this header's validity at all. There are currently 5 distinct levels for a
-  trace :
+  These filters are used to selectively include or exclude events depending on
+  their level of importance. For example a developer might need to know
+  precisely where in the code an HTTP header was considered invalid while the
+  end user may not even care about this header's validity at all. There are
+  currently 5 distinct levels for a trace :
 
       user         this will report information that are suitable for use by a
                    regular haproxy user who wants to observe his traffic.
@@ -2658,14 +2658,9 @@ trace <source> level [<level>]
                    without much detail. Most sources will set this as the
                    default level to ease operations.
 
-      payload      in addition to what is reported at the "user" level, it will
-                   also display more detailed information about the contents,
-                   which may be HTTP headers, or unencoded contents.
-
-      proto        in addition to what is reported at the "payload" level, it
-                   also display protocol-level information. This can for
-                   example be the raw data exchanged over the wire after
-                   encoding or frames received before decoding.
+      proto        in addition to what is reported at the "user" level, it also
+                   displays protocol-level updates. This can for example be the
+                   frame types or HTTP headers after decoding.
 
       state        in addition to what is reported at the "proto" level, it
                    will also display state transitions (or failed transitions)
@@ -2673,6 +2668,9 @@ trace <source> level [<level>]
                    perform an operation while the "proto" level only shows
                    the final operation.
 
+      data         in addition to what is reported at the "state" level, it
+                   will also include data transfers between the various layers.
+
       developer    it reports everything available, which can include advanced
                    information such as "breaking out of this loop" that are
                    only relevant to a developer trying to understand a bug that

diff --git a/include/proto/trace.h b/include/proto/trace.h
index 5df7107c46fa137429164591e9de17ee5f668328..726fefdbf900cd3cfbf970ea500d8cb50b9e6e01 100644 (file)
--- a/include/proto/trace.h
+++ b/include/proto/trace.h
@@ -55,8 +55,8 @@
 #define TRACE_USER(msg, mask, ...)                     \
        trace(TRACE_LEVEL_USER,      (mask), TRACE_SOURCE, ist(TRC_LOC), TRC_5ARGS(__VA_ARGS__,,,,,), ist(msg))
 
-#define TRACE_PAYLOAD(msg, mask, ...)  \
-       trace(TRACE_LEVEL_PAYLOAD,   (mask), TRACE_SOURCE, ist(TRC_LOC), TRC_5ARGS(__VA_ARGS__,,,,,), ist(msg))
+#define TRACE_DATA(msg, mask, ...)  \
+       trace(TRACE_LEVEL_DATA,   (mask), TRACE_SOURCE, ist(TRC_LOC), TRC_5ARGS(__VA_ARGS__,,,,,), ist(msg))
 
 #define TRACE_PROTO(msg, mask, ...)    \
        trace(TRACE_LEVEL_PROTO,     (mask), TRACE_SOURCE, ist(TRC_LOC), TRC_5ARGS(__VA_ARGS__,,,,,), ist(msg))

diff --git a/include/types/trace.h b/include/types/trace.h
index b3f418f6b238338c441dbb09db7d35641ac3af7b..03eb7dbc99e94e00d6fab9ac3f35befdd0922e0b 100644 (file)
--- a/include/types/trace.h
+++ b/include/types/trace.h
@@ -78,12 +78,15 @@ enum trace_state {
        TRACE_STATE_RUNNING,      // waiting for the stop or pause conditions
 };
 
+/* trace levels, from least detailed to most detailed. Traces emitted at a
+ * lower level are always reported at higher levels.
+ */
 enum trace_level {
        TRACE_LEVEL_USER = 0,     // info useful to the end user
-       TRACE_LEVEL_PAYLOAD,      // add info relevant to the payload
-       TRACE_LEVEL_PROTO,        // add info relevant to the protocol
-       TRACE_LEVEL_STATE,        // add info relevant to the state machine
-       TRACE_LEVEL_DEVELOPER,    // add info useful only to the developer
+       TRACE_LEVEL_PROTO,        // also report protocol-level updates
+       TRACE_LEVEL_STATE,        // also report state changes
+       TRACE_LEVEL_DATA,         // also report data exchanges
+       TRACE_LEVEL_DEVELOPER,    // functions entry/exit and any other developer info
 };
 
 enum trace_lockon {

diff --git a/src/trace.c b/src/trace.c
index e44fa8421600af529977962640c49691314f1086..7769b5d26a361e2cd548fbed5ff3832285dac8ed 100644 (file)
--- a/src/trace.c
+++ b/src/trace.c
@@ -282,7 +282,7 @@ static int cli_parse_trace(char **args, char *payload, struct appctx *appctx, vo
                               "Supported commands:\n"
                               "  event   : list/enable/disable source-specific event reporting\n"
                               //"  filter  : list/enable/disable generic filters\n"
-                              "  level   : list/set detail level\n"
+                              "  level   : list/set trace reporting level\n"
                               "  lock    : automatic lock on thread/connection/stream/...\n"
                               "  pause   : pause and automatically restart after a specific event\n"
                               "  sink    : list/set event sinks\n"
@@ -386,16 +386,16 @@ static int cli_parse_trace(char **args, char *payload, struct appctx *appctx, vo
                const char *name = args[3];
 
                if (!*name) {
-                       chunk_printf(&trash, "Supported detail levels for source %s:\n", src->name.ptr);
+                       chunk_printf(&trash, "Supported trace levels for source %s:\n", src->name.ptr);
                        chunk_appendf(&trash, "  %c user       : information useful to the end user\n",
                                      src->level == TRACE_LEVEL_USER ? '*' : ' ');
-                       chunk_appendf(&trash, "  %c payload    : add information relevant to the payload\n",
-                                     src->level == TRACE_LEVEL_PAYLOAD ? '*' : ' ');
-                       chunk_appendf(&trash, "  %c proto      : add information relevant to the protocol\n",
+                       chunk_appendf(&trash, "  %c proto      : also protocol-level updates\n",
                                      src->level == TRACE_LEVEL_PROTO ? '*' : ' ');
-                       chunk_appendf(&trash, "  %c state      : add information relevant to the state machine\n",
+                       chunk_appendf(&trash, "  %c state      : also report internal state changes\n",
                                      src->level == TRACE_LEVEL_STATE ? '*' : ' ');
-                       chunk_appendf(&trash, "  %c developer  : add information useful only to the developer\n",
+                       chunk_appendf(&trash, "  %c data       : also report data transfers\n",
+                                     src->level == TRACE_LEVEL_DATA ? '*' : ' ');
+                       chunk_appendf(&trash, "  %c developer  : also report information useful only to the developer\n",
                                      src->level == TRACE_LEVEL_DEVELOPER ? '*' : ' ');
                        trash.area[trash.data] = 0;
                        return cli_msg(appctx, LOG_WARNING, trash.area);
@@ -403,12 +403,12 @@ static int cli_parse_trace(char **args, char *payload, struct appctx *appctx, vo
 
                if (strcmp(name, "user") == 0)
                        HA_ATOMIC_STORE(&src->level, TRACE_LEVEL_USER);
-               else if (strcmp(name, "payload") == 0)
-                       HA_ATOMIC_STORE(&src->level, TRACE_LEVEL_PAYLOAD);
                else if (strcmp(name, "proto") == 0)
                        HA_ATOMIC_STORE(&src->level, TRACE_LEVEL_PROTO);
                else if (strcmp(name, "state") == 0)
                        HA_ATOMIC_STORE(&src->level, TRACE_LEVEL_STATE);
+               else if (strcmp(name, "data") == 0)
+                       HA_ATOMIC_STORE(&src->level, TRACE_LEVEL_DATA);
                else if (strcmp(name, "developer") == 0)
                        HA_ATOMIC_STORE(&src->level, TRACE_LEVEL_DEVELOPER);
                else