Modified: trunk/ChangeLog (280822 => 280823)
--- trunk/ChangeLog 2021-08-10 02:54:55 UTC (rev 280822)
+++ trunk/ChangeLog 2021-08-10 03:11:48 UTC (rev 280823)
@@ -1,3 +1,14 @@
+2021-08-09 Myles C. Maxfield <[email protected]>
+
+ Update logging docs after r280758
+ https://bugs.webkit.org/show_bug.cgi?id=228899
+
+ Reviewed by Fujii Hironori.
+
+ Add more information about logging.
+
+ * Introduction.md:
+
2021-08-05 Michael Catanzaro <[email protected]>
GCC 11 builds should use -Wno-array-bounds, -Wno-nonnull
Modified: trunk/Introduction.md (280822 => 280823)
--- trunk/Introduction.md 2021-08-10 02:54:55 UTC (rev 280822)
+++ trunk/Introduction.md 2021-08-10 03:11:48 UTC (rev 280823)
@@ -1344,24 +1344,79 @@
# Logging in WebKit
-Some places in WebKit use a macro called `LOG_WITH_STREAM`. Here's an example invocation:
+## Setup
+Each framework (WebCore, WebKit, WebKitLegacy, WTF) enable their own logging infrastructure independently (though the infrastructure itself is shared). If you want to log a message, `#include` the relevant framework's `Logging.h` header. Then, you can use the macros below.
+
+Beware that you can't `#include` multiple framework's `Logging.h` headers at the same time - they each define a macro `LOG_CHANNEL_PREFIX` which will conflict with each other. Only `#include` the `Logging.h` header from your specific framework.
+
+If you want to do more advanced operations, like searching through the list of log channels, `#include` your framework's `LogInitialization.h` header. These do not conflict across frameworks, so you can do something like
+
```
+#include "LogInitialization.h"
+#include <WebCore/LogInitialization.h>
+#include <WTF/LogInitialization.h>
+```
+
+Indeed, WebKit does this to initialize all frameworks' log channels during Web Process startup.
+
+## Logging messages
+
+There are a few relevant macros for logging messages:
+
+- `LOG()`: Log a printf-style message in debug builds. Requires you to name a logging channel to output to.
+- `LOG_WITH_STREAM()` Log an iostream-style message in debug builds. Requires you to name a logging channel to output to.
+- `RELEASE_LOG()`: Just like `LOG()` but logs in both debug and release builds. Requires you to name a logging channel to output to.
+- `WTFLogAlways()`: Mainly for local debugging, unconditionally output a message. Does not require a logging channel to output to.
+
+Here's an example invocation of `LOG()`:
+
+```
+LOG(MediaQueries, "HTMLMediaElement %p selectNextSourceChild evaluating media queries", this);
+```
+
+That first argument is a log channel. These have 2 purposes:
+
+- Individual channels can be enabled/disabled independently (So you can get all the WebGL logging without getting any Loading logging)
+- When multiple channels are enabled, and you're viewing the logs, you can search/filter by the channel
+
+Here's an example invocation of `LOG_WITH_STREAM()`:
+
+```
LOG_WITH_STREAM(Scrolling, stream << "ScrollingTree::commitTreeState - removing unvisited node " << nodeID);
```
-The first argument is the _log channel_ and the second is the _log content_. By default, this logging is enabled in
-debug builds and disabled in release builds (see definition of `LOG_DISABLED`).
+The macro sets up a local variable named `stream` which the second argument can direct messages to. The second argument is a collection of statements - not expressions like `LOG()` and `RELEASE_LOG()`. So, you can do things like this:
-The only logs that will be printed are those whose channels you have enabled. You can specify the channels you want to
-enable by constructing a comma-separated list with the following syntax:
+```
+LOG_WITH_STREAM(TheLogChannel,
+ for (const auto& something : stuffToLog)
+ stream << " " << something;
+);
+```
-* `ChannelName` to enable logging for this channel
-* `all` to enable logging for all channels
-* `-ChannelName` to disable logging for this channel
+The reason why (most of) these use macros is so the entire thing can be compiled out when logging is disabled. Consider this:
-Where you specify this list depends on the platform you are running WebKit on.
+```
+LOG(TheLogChannel, "The result is %d", someSuperComplicatedCalculation());
+```
+If these were not macros, you'd have to pay for `someSuperComplicatedCalculation()` whether logging is enabled or not.
+
+## Enabling and disabling log channels
+
+Channels are enabled/disabled at startup by passing a carefully crafted string to `initializeLogChannelsIfNecessary()`. On the macOS and iOS ports, this string comes from the _defaults_ database. On other UNIX systems and Windows, it comes from environment variables.
+
+You can read the grammar of this string in `initializeLogChannelsIfNecessary()`. Here is an example:
+
+```
+WebGL -Loading
+```
+
+You can also specify the string `all` to enable all logging.
+
+On macOS/iOS and Windows, each framework has its own individually supplied string that it uses to enable its own logging channels. On Linux, all frameworks share the same string.
+
### Linux
Set the `WEBKIT_DEBUG` environment variable.
@@ -1370,23 +1425,28 @@
WEBKIT_DEBUG=Scrolling Tools/Scripts/run-minibrowser --gtk --debug
```
-### Mac
+### macOS
-Set a value for the `WebCoreLogging` key in [standardUserDefaults](https://developer.apple.com/documentation/foundation/nsuserdefaults/1416603-standarduserdefaults).
+On macOS, you can supply these strings with these terminal commands:
-You may also pass this key and value as an argument:
-
```
-Tools/Scripts/run-minibrowser --debug -WebCoreLogging Scrolling
+% defaults write com.apple.WebKit.WebContent WTFLogging "Threading"
+% defaults write com.apple.WebKit.WebContent WebCoreLogging "WebGL"
+% defaults write com.apple.WebKit.WebContent WebKit2Logging "ResourceLoadStatistics"
```
-or set the key and value on the [NSGlobalDomain](https://developer.apple.com/documentation/foundation/nsglobaldomain).
+You may also need to specify these strings to `com.apple.WebKit.WebContent.Development`, the global domain, or the Safari container, depending on what you're running.
+You may also pass this key and value as an argument:
+
```
-defaults write NSGlobalDomain WebCoreLogging -string Scrolling
-Tools/Scripts/run-minibrowser --debug
+Tools/Scripts/run-minibrowser --debug -WebCoreLogging Scrolling
```
### Windows
Set the `WebCoreLogging` environment variable.
+
+## Adding a new log channel
+
+Simply add a line to your framework's `Logging.h` header. Depending on how the accompanying `Logging.cpp` file is set up, you may need to add a parallel line there. That should be all you need. It is acceptable to have log channels in different frameworks with the same name - this is what `LOG_CHANNEL_PREFIX` is for.
