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 8b3f6f6..1dd52f5 100644
--- a/doc/management.txt
+++ b/doc/management.txt
@@ -2642,15 +2642,15 @@
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 @@
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 @@
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 5df7107..726fefd 100644
--- 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 b3f418f..03eb7db 100644
--- a/include/types/trace.h
+++ b/include/types/trace.h
@@ -78,12 +78,15 @@
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 e44fa84..7769b5d 100644
--- a/src/trace.c
+++ b/src/trace.c
@@ -282,7 +282,7 @@
"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 @@
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 @@
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