Skip to content

Commit

Permalink
Chromium Visual Debugger tool initial release
Browse files Browse the repository at this point in the history
The Visual Debugger is essentially a type aware printf that is useful
for debugging and prototyping.

See READMEs for more info:
//components/viz/service/debugger/README.md
//tools/visual_debugger/README.md

Bug: 1228113
Change-Id: I34d31dd75fb6d3f860a5f463c8f621bdaf752e0d
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3538742
Reviewed-by: Sadrul Chowdhury <sadrul@chromium.org>
Reviewed-by: Bruce Dawson <brucedawson@chromium.org>
Commit-Queue: Peter McNeeley <petermcneeley@chromium.org>
Cr-Commit-Position: refs/heads/main@{#988199}
  • Loading branch information
petermcneeleychromium authored and Chromium LUCI CQ committed Apr 2, 2022
1 parent e5f0b2f commit ad3b2a5
Show file tree
Hide file tree
Showing 12 changed files with 1,616 additions and 1 deletion.
10 changes: 9 additions & 1 deletion components/viz/service/debugger/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,15 @@
The Viz Remote Debugger is a debug only connection that allows an active chromium instance to send graphical and text debug information to a remote client for display.

### Motivation
[Visual Debugger one-pager](https://docs.google.com/document/d/1s2OLZcUrUxXRxOD8nR4giNRnCQZcdtXBp4DUI_Fb2GU/edit?usp=sharing).
- Much of the debugging of internal chromium is printfs even though many aspects of the chromium code is highly graphics focused.
- Developers are constantly recompiling to add new printf only to delete it when committing into chromium repo to avoid global printf spamming.
- Using local chrome itself to display debug information runs into the “measurement problem” (For example visually debugging damages locally).

### Advantages

- Visualization of graphical objects as graphic elements rather than text.
- Debugging can be shared across the codebase and among developers.
- Allow for more rapid and lower overhead debugging since code is guaranteed not to be in official builds.


### Usage
Expand Down
3 changes: 3 additions & 0 deletions tools/visual_debugger/OWNERS
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
petermcneeley@google.com
sadrul@chromium.org

48 changes: 48 additions & 0 deletions tools/visual_debugger/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@

# //tools/visual_debugger/

## Chromium Visual Debugger App

The Chromium Visual Debugger App is the viewer for the debug stream from a (remote) chromium instance.
For information on the chromium integration of debug capture see: `//components/viz/service/debugger/README.md`

### Launching
To use the Visual Debugger, Chromium must be launch with remote debugging support.

` --remote-debugging-port=7777`

To launch the Debugging App simply run the python server from this directory. The default port is 7777.

` ./server.py [portnumber]`

This command will also launch the debugger as a Web App in a separate instance of the default browser.

In official builds (`is_official_build=true` gn arg) the debugger is disabled by default but can be force enabled locally with the flag below in **args.gn**.

` use_viz_debugger=true`

### Usage

Once the Debugging App launches one should be able to simply click **Connect** to establish a remote debugging stream to the live instance of chromium.

The in App filters `frame.root.quad` and `frame.root.damage` have been provided by default to give immediate feedback and intuition. The debug macros corresponding to these filters, and all others, can be found directly in the source.

[Default Filter Debug Macros](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/display.cc;l=640;drc=5af781c328bdc091651764b5d9ea0f6d77828fed?q=display.cc&ss=chromium%2Fchromium%2Fsrc)

### Operation
The debugging macros feed information into the VizDebugger static instance. At the end of each frame this cached information is fed upstream and eventually reaches the remote client.

![Viz Debugger Communication](visual_debugger_communications.png)


### Performance
The Debugger App preforms nominally in most basic debugging situations.
Excessive debug logging, specifically text, can make the App feel sluggish.
It is recommended to delete unused filters and disable filters to improve App performance.


### Security

For official builds all visual debug macros are compiled out and the VizDebugger is reduced to a selective few method stubs. This means there are no security concerns for this system with exception of mutable side effects in the creation of input variables to the logging macros. These concerns for mutable side effects already exist for any other code; so no special attention is warranted for these macros.

For non-official (debug) builds the dev-tools remote debugging port command line argument must be provided for the viz debugger to collect and stream data. Thus the security of this new system is identical to that of the remote dev tools for the case of debugging builds.

0 comments on commit ad3b2a5

Please sign in to comment.