WSDG: Minor logging documentation enhancements

This commit is contained in:
João Valverde 2023-02-22 08:18:14 +00:00
parent 9730610c0b
commit 91366f56f2
1 changed files with 25 additions and 20 deletions

View File

@ -270,26 +270,27 @@ As with the Unix-like build described above, you can run Wireshark from the buil
[#ChSrcLogging] [#ChSrcLogging]
==== Wireshark Logging ==== Wireshark Logging
To assist in development and investigation of bugs, Wireshark has been equipped with a configurable logging system. Wireshark has a flexible logging system to assist in development and troubleshooting.
Configuration takes into account what, when, where to output log messages. Logging configuration takes into account what, when and where to output diagnostic messages.
* The 'what generates log messages' is defined through logging domain(s). * The 'what generates log messages' is defined through logging domain(s).
* The 'when it generates log messages' is defined through the logging level. * The 'when it generates log messages' is defined through the logging level.
* The 'where it outputs log messages' is defined through the output channel(s). * The 'where it outputs log messages' is defined through the output channel(s).
The details of configuring and use of the logging system are explained in the following sections. The details to configure and use the logging system are explained in the following sections.
[#ChSrcLoggingDomains] [#ChSrcLoggingDomains]
===== Logging Domains ===== Logging Domains
Any part of Wireshark can be defined as its own logging domain. This is already done for most of the internals of Wireshark, e.g., "Main", "Capture", "Epan", "GUI", but also dissectors can define their own logging domain. Any string can be used as ID for a logging domain. Any part of Wireshark can be assigned a logging domain. This is already done for most of the internals of Wireshark,
e.g., "Main", "Capture", "Epan", "GUI". The domains are defined in the `ws_log_defs.h` header but dissectors should
define their own logging domain. Any string can be used as ID for a logging domain.
[#ChSrcLoggingLevels] [#ChSrcLoggingLevels]
===== Logging Levels ===== Logging Levels
The following logging levels are defined: The following logging levels are defined:
* echo
* error * error
* critical * critical
* warning * warning
@ -298,16 +299,20 @@ The following logging levels are defined:
* debug * debug
* noisy * noisy
By default logging output is generated for logging level message and above. If the logging level is lowered or raised all log output generated at or above this level is sent to the log output. By default logging output is generated for logging level "message" and above. If the logging level is lowered or raised
all log output generated at or above this level is sent to the log output. Note that release builds by default do not
generate log output for the logging levels debug and noisy.
Note that release builds do not generate log output for the logging levels debug and noisy. There is also a special "echo" logging level used exclusively for temporary debugging print outs (usually
via the `WS_DEBUG_HERE` macro).
[#ChSrcLoggingOutput] [#ChSrcLoggingOutput]
===== Logging Output ===== Logging Output
By default logging output is sent to stderr. Unless a program sets a flag to send log messages at or below logging level info to stdout. Another way a program can divert the output of all log messages is by registering its own log writer. These measures can be taken when the normal streams, i.e. stderr and/or stdout, are already used otherwise. By default logging output is sent to stderr. In addition to that it is possible to configure a log file. This collects all log output to the
file, besides the normal output streams. The output can then be read in a text editor or used with other text processing tools.
The more user friendly way to collect log messages is to set a log file. This collects all log output, besides it being sent to the normal output stream. A program can also register its own log writer when the standard facilities are insufficient or special handling is required.
[#ChSrcConfigureLogging] [#ChSrcConfigureLogging]
===== Configure Logging ===== Configure Logging
@ -317,15 +322,15 @@ Logging can be configured through either environment variables or command line p
The following environment variables and command line parameters are used by the logging system: The following environment variables and command line parameters are used by the logging system:
WIRESHARK_LOG_DOMAIN, WIRESHARK_LOG_DOMAINS, or --log-domain, --log-domains:: WIRESHARK_LOG_DOMAIN, WIRESHARK_LOG_DOMAINS, or --log-domain, --log-domains::
These are the domain(s) which are to generate log messages. Multiple domains can be concatenated with commas or semicolons. This is a filter for the domain(s) which are to generate log messages.
WIRESHARK_LOG_LEVEL, or --log-level:: WIRESHARK_LOG_LEVEL, or --log-level::
This is the level (below critical) for which log messages are to be generated. This is used for all configured domains. This is the level (below critical) for which log messages are to be generated. This is used for all configured domains.
WIRESHARK_LOG_DEBUG, or --log-debug:: WIRESHARK_LOG_DEBUG, or --log-debug::
These domain(s) will generate debug level log messages regardless of the log level and log domains configured. Multiple domains can be concatenated with commas or semicolons. These domain(s) will generate debug level log messages regardless of the log level and log domains configured.
WIRESHARK_LOG_NOISY, or --log_noisy:: WIRESHARK_LOG_NOISY, or --log_noisy::
These domain(s) will generate noisy level log messages regardless of the log level and log domains configured. Multiple domains can be concatenated with commas or semicolons. These domain(s) will generate noisy level log messages regardless of the log level and log domains configured.
Note that the selected log domain(s) can be inverted by prefixing the (first) domain with an exclamation mark. Multiple domains can be concatenated using commas or semicolons. The match can be inverted by prefixing the domain(s) list with an exclamation mark.
[#ChSrcTrapsLogging] [#ChSrcTrapsLogging]
==== Traps Set By Logging ==== Traps Set By Logging
@ -338,29 +343,28 @@ WIRESHARK_LOG_FATAL, or --log_fatal::
This is the level for which log messages are fatal. This can either be "critical" or "warning" level. This is the level for which log messages are fatal. This can either be "critical" or "warning" level.
WIRESHARK_LOG_FATAL_DOMAIN, WIRESHARK_LOG_FATAL_DOMAINS, or --log-fatal-domain, --log-fatal-domains:: WIRESHARK_LOG_FATAL_DOMAIN, WIRESHARK_LOG_FATAL_DOMAINS, or --log-fatal-domain, --log-fatal-domains::
These are the domain(s) where output of a log message is fatal. These are the domain(s) where output of a log message is fatal. This is less commonly used than the fatal log level setting above.
[#ChSrcLoggingApi] [#ChSrcLoggingApi]
==== Logging APIs ==== Logging APIs
The logging API can be found in `wsutil/wslog.h`. The logging API can be found in `wsutil/wslog.h`.
To use the logging API for your code add the definition of the ID of your logging domain right after including `config.h` and make sure `wslog.h` is included. For example: To use the logging API for your code add the definition of the ID of your logging domain right after including `config.h`. For example:
[source,c] [source,c]
---- ----
/* My code doing something awesome */ /* My code doing something awesome */
#include <config.h> #include "config.h"
#define WS_LOG_DOMAIN "MyCode" #define WS_LOG_DOMAIN "MyCode"
... #include <wireshark.h>
#include <wsutil/wslog.h>
... ...
---- ----
Populate your code with the applicable function calls to generate log messages when enabled. The following convenience macros are provided: Populate your code with the applicable function calls to generate log messages when enabled. The following convenience macros are provided:
* `WS_DEBUG_HERE()`
* `ws_error()` * `ws_error()`
* `ws_critical()` * `ws_critical()`
* `ws_warning()` * `ws_warning()`
@ -369,7 +373,8 @@ Populate your code with the applicable function calls to generate log messages w
* `ws_debug()` * `ws_debug()`
* `ws_noisy()` * `ws_noisy()`
All these take `printf()` style parameters. While these calls can remain in the code, `WS_DEBUG_HERE` should be used for development purposes only and not appear in final delivery of the code. All these take `printf()` style parameters. There is also a `WS_DEBUG_HERE` macro that is always active and outputs to a special "echo"
domain for temporary debug print outs. `WS_DEBUG_HERE` should be used for development purposes only and not appear in final delivery of the code.
[#ChSrcUnixDebug] [#ChSrcUnixDebug]
==== Unix-Like Platforms ==== Unix-Like Platforms