Skip to content

Commit fc51bd9

Browse files
litherumlitherum
committed
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: Canonical link: https://commits.webkit.org/240386@main git-svn-id: https://svn.webkit.org/repository/webkit/trunk@280823 268f45cc-cd09-0410-ab3c-d52691b4dbfc
1 parent 50e733f commit fc51bd9

2 files changed

Lines changed: 88 additions & 17 deletions

File tree

‎ChangeLog‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
2021-08-09 Myles C. Maxfield <mmaxfield@apple.com>
2+
3+
Update logging docs after r280758
4+
https://bugs.webkit.org/show_bug.cgi?id=228899
5+
6+
Reviewed by Fujii Hironori.
7+
8+
Add more information about logging.
9+
10+
* Introduction.md:
11+
112
2021-08-05 Michael Catanzaro <mcatanzaro@gnome.org>
213

314
GCC 11 builds should use -Wno-array-bounds, -Wno-nonnull

‎Introduction.md‎

Lines changed: 77 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1344,23 +1344,78 @@ FIXME: Talk about how to debug API tests.
13441344

13451345
# Logging in WebKit
13461346

1347-
Some places in WebKit use a macro called `LOG_WITH_STREAM`. Here's an example invocation:
1347+
## Setup
1348+
1349+
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.
1350+
1351+
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.
1352+
1353+
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
1354+
1355+
```
1356+
#include "LogInitialization.h"
1357+
#include <WebCore/LogInitialization.h>
1358+
#include <WTF/LogInitialization.h>
1359+
```
1360+
1361+
Indeed, WebKit does this to initialize all frameworks' log channels during Web Process startup.
1362+
1363+
## Logging messages
1364+
1365+
There are a few relevant macros for logging messages:
1366+
1367+
- `LOG()`: Log a printf-style message in debug builds. Requires you to name a logging channel to output to.
1368+
- `LOG_WITH_STREAM()` Log an iostream-style message in debug builds. Requires you to name a logging channel to output to.
1369+
- `RELEASE_LOG()`: Just like `LOG()` but logs in both debug and release builds. Requires you to name a logging channel to output to.
1370+
- `WTFLogAlways()`: Mainly for local debugging, unconditionally output a message. Does not require a logging channel to output to.
1371+
1372+
Here's an example invocation of `LOG()`:
1373+
1374+
```
1375+
LOG(MediaQueries, "HTMLMediaElement %p selectNextSourceChild evaluating media queries", this);
1376+
```
1377+
1378+
That first argument is a log channel. These have 2 purposes:
1379+
1380+
- Individual channels can be enabled/disabled independently (So you can get all the WebGL logging without getting any Loading logging)
1381+
- When multiple channels are enabled, and you're viewing the logs, you can search/filter by the channel
1382+
1383+
Here's an example invocation of `LOG_WITH_STREAM()`:
13481384

13491385
```
13501386
LOG_WITH_STREAM(Scrolling, stream << "ScrollingTree::commitTreeState - removing unvisited node " << nodeID);
13511387
```
13521388

1353-
The first argument is the _log channel_ and the second is the _log content_. By default, this logging is enabled in
1354-
debug builds and disabled in release builds (see definition of `LOG_DISABLED`).
1389+
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:
1390+
1391+
```
1392+
LOG_WITH_STREAM(TheLogChannel,
1393+
for (const auto& something : stuffToLog)
1394+
stream << " " << something;
1395+
);
1396+
```
1397+
1398+
The reason why (most of) these use macros is so the entire thing can be compiled out when logging is disabled. Consider this:
1399+
1400+
```
1401+
LOG(TheLogChannel, "The result is %d", someSuperComplicatedCalculation());
1402+
```
1403+
1404+
If these were not macros, you'd have to pay for `someSuperComplicatedCalculation()` whether logging is enabled or not.
1405+
1406+
## Enabling and disabling log channels
1407+
1408+
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.
13551409

1356-
The only logs that will be printed are those whose channels you have enabled. You can specify the channels you want to
1357-
enable by constructing a comma-separated list with the following syntax:
1410+
You can read the grammar of this string in `initializeLogChannelsIfNecessary()`. Here is an example:
13581411

1359-
* `ChannelName` to enable logging for this channel
1360-
* `all` to enable logging for all channels
1361-
* `-ChannelName` to disable logging for this channel
1412+
```
1413+
WebGL -Loading
1414+
```
13621415

1363-
Where you specify this list depends on the platform you are running WebKit on.
1416+
You can also specify the string `all` to enable all logging.
1417+
1418+
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.
13641419

13651420
### Linux
13661421

@@ -1370,23 +1425,28 @@ Set the `WEBKIT_DEBUG` environment variable.
13701425
WEBKIT_DEBUG=Scrolling Tools/Scripts/run-minibrowser --gtk --debug
13711426
```
13721427

1373-
### Mac
1374-
1375-
Set a value for the `WebCoreLogging` key in [standardUserDefaults](https://developer.apple.com/documentation/foundation/nsuserdefaults/1416603-standarduserdefaults).
1428+
### macOS
13761429

1377-
You may also pass this key and value as an argument:
1430+
On macOS, you can supply these strings with these terminal commands:
13781431

13791432
```
1380-
Tools/Scripts/run-minibrowser --debug -WebCoreLogging Scrolling
1433+
% defaults write com.apple.WebKit.WebContent WTFLogging "Threading"
1434+
% defaults write com.apple.WebKit.WebContent WebCoreLogging "WebGL"
1435+
% defaults write com.apple.WebKit.WebContent WebKit2Logging "ResourceLoadStatistics"
13811436
```
13821437

1383-
or set the key and value on the [NSGlobalDomain](https://developer.apple.com/documentation/foundation/nsglobaldomain).
1438+
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.
1439+
1440+
You may also pass this key and value as an argument:
13841441

13851442
```
1386-
defaults write NSGlobalDomain WebCoreLogging -string Scrolling
1387-
Tools/Scripts/run-minibrowser --debug
1443+
Tools/Scripts/run-minibrowser --debug -WebCoreLogging Scrolling
13881444
```
13891445

13901446
### Windows
13911447

13921448
Set the `WebCoreLogging` environment variable.
1449+
1450+
## Adding a new log channel
1451+
1452+
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.

0 commit comments

Comments
 (0)