Currently we are not filtering the unset (NULL) domain, on
the assumption that every log call should belong to a defined
domain.
However there are still many places in the codebase where this isn't
true and the fact that the null/default domain name is omitted from
the output and never filtered is probably surprising and user-unfriendly.
Users might understandably assume the filtering is buggy.
Give an indication, such as (none)-MESSAGE, to make this more
obvious.
The --log-debug and --log-noisy now accepts a '!' to invert the
match and disable the debug (noisy respectively) log level for
the listed domains.
Note this is different from --log-domains, that option
enables/disables the entire log domain itself, regardless of log
level.
ws_log_domains.h needs to be included before wslog.h to be used
to define WS_LOG_DOMAIN. Also the definition for enum ws_log_level
needs to be exported for other APIs so move that to ws_log_domains.h
and rename the file to ws_log_defs.h to reflect the new scope.
This is intended to replace logging in dissectors that has a
debug level with #ifdef DEBUG_foo and an extra level guarded
by a #ifdef DEBUG_EXTRA_foo.
But generally it can be used as another level of granularity
for debugging output, to avoid flooding the log with too
much information with typical usage.
Rename the filter functions without the unnecessary 'str'
suffix.
Option --log-debug or WIRESHARK_LOG_DEBUG is a list
of domains that are set to a "debug" log level. This
takes precedence over the normal log level and domain
filter options.
Enviroment variable WIRESHARK_LOG_FATAL and command line
option --log-fatal set the fatal log level. Messages with
fatal or highr priority cause the program to abort. By
default the fatal level is "error", but it can be set to
"critical" or "warning" with this option.
Domain filter expressions starting with '!' invert the match.
Only domains that do not match become active. Note that '!'
must be the first character in the filter and applies to the
whole expression.
Add macros to round to multiples of 2, 4, 8, 16, and 32.
Use them instead of independently defined macros.
(We don't define a general "round to a power of 2" macro to avoid the
risk of somebody passing something other than a power of 2 to it.)
A domain filter can be given in the environment variable
'WS_LOG_DOMAINS' or in a command-line options "--log-domains".
The filter is specified as a comma separated case insensitive list,
for example:
./tshark --log-domains=main,capture
Domain data type switches from an enum to a string. There is no
constaint on adding new domains, neither in code or at runtime.
The string format is arbitrary, only positive matches will produce
output.
Experience has shown that:
1. The current logging methods are not very reliable or practical.
A logging bitmask makes little sense as the user-facing interface (who
would want debug but not crtical messages for example?); it's
computer-friendly and user-unfriendly. More importantly the console
log level preference is initialized too late in the startup process
to be used for the logging subsystem and that fact raises a number
of annoying and hard-to-fix usability issues.
2. Coding around G_MESSAGES_DEBUG to comply with our log level mask
and not clobber the user's settings or not create unexpected log misses
is unworkable and generally follows the principle of most surprise.
The fact that G_MESSAGES_DEBUG="all" can leak to other programs using
GLib is also annoying.
3. The non-structured GLib logging API is very opinionated and lacks
configurability beyond replacing the log handler.
4. Windows GUI has some special code to attach to a console,
but it would be nice to abstract away the rest under a single
interface.
5. Using this logger seems to be noticeably faster.
Deprecate the console log level preference and extend our API to
implement a log handler in wsutil/wslog.h to provide easy-to-use,
flexible and dependable logging during all execution phases.
Log levels have a hierarchy, from most verbose to least verbose
(debug to error). When a given level is set everything above that
is also enabled.
The log level can be set with an environment variable or a command
line option (parsed as soon as possible but still later than the
environment). The default log level is "message".
Dissector logging is not included because it is not clear what log
domain they should use. An explosion to thousands of domains is
not desirable and putting everything in a single domain is probably
too coarse and noisy. For now I think it makes sense to let them do
their own thing using g_log_default_handler() and continue using the
G_MESSAGES_DEBUG mechanism with specific domains for each individual
dissector.
In the future a mechanism may be added to selectively enable these
domains at runtime while trying to avoid the problems introduced
by G_MESSAGES_DEBUG.
Add a generic function to write content to file. Use this on write
TLS session keys from UI and tshark, and for export objects.
Remove the now unused export_object_ui.[ch].
The GLib documentation says G_STRLOC includes the function name
but that is a lie[1]. Change ws_debug() to not use G_STRLOC and receive
__FILE__, __LINE__ and G_STRFUNC separately instead.
[1]https://bugzilla.gnome.org/show_bug.cgi?id=69097
Default to taking the VLAN ID into account when reassembling only
for private IPv4 addresses as defined by RFC 1918 and for link-local
addresses. Otherwise, do not take the VLAN ID into account unless
the "Enable stricter conversation tracking heuristics" preference
is enabled. Fixes#14356.
Replace most instances of ws_debug_printf() except in
epan/dissectors and dissector plugins.
Some replacements use printf(), some use ws_debug(), and
some were removed because they were dead or judged to be
temporary.
Use a void expression instead of removing the expression
entirely. Under certain conditions, for example as the only
statement in an if() conditional, removing the assertion
will generate compiler warnings.
Currently our build generates very many warnings if
G_DISABLE_ASSERT is defined.
Add ws_assert() and ws_assert_not_reached() to incrementally
replace existing assertions and then disable them using
WS_DISABLE_ASSERT.
Assertions are disabled with CMake build type Release.
By default the build type is RelWithDebInfo so the current
behaviour of enabling assertions by default is (for now) preserved.
Add some notes to README.Developer.
Most of the time, the return value tells us nothing useful, as we've
already decided that we're perfectly willing to live with string
truncation. Hopefully this keeps Coverity from whining that those
routines could return an error code (NARRATOR: They don't) and thus that
we're ignoring the possibility of failure (as indicated, we've already
decided that we can live with string truncation, so truncation is *NOT*
a failure).