[docs] Introduce an initial "Console Policy" for DevTools.

This will serve as a reference to point Chromium teams to when it comes to what should be logged to the DevTools Console panel and what not. Bug: 338403584 Change-Id: Id3b34767c8008b6c4b4c533b8ea38620385cdbd7 Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/7004666 Reviewed-by: Meysam Sarabadani <meysarabadani@chromium.org> Commit-Queue: Meysam Sarabadani <meysarabadani@chromium.org> Auto-Submit: Benedikt Meurer <bmeurer@chromium.org>
2026-09-28 21:24:26 +08:00 · 2025-10-02 02:48:41 -07:00
parent f555149ccb
commit 8015771d44
6 changed files with 146 additions and 0 deletions
@@ -60,6 +60,7 @@ below.**

 ### Policies

+*   [Chromium DevTools Console Policy](./policy/console-policy.md)
 *   [Chromium DevTools Slow-Close Policy](./policy/slow-close.md)
 *   [DevTools Page Zoom Accessibility Policy](./policy/gar-page-zoom-policy.md)

@@ -3,5 +3,6 @@
 This folder contains the policies relevant to the development of the Chromium
 DevTools.

+1. [Chromium DevTools Console Policy](./console-policy.md)
 1. [Chromium DevTools Slow-Close Policy](./slow-close.md)
 2. [DevTools Page Zoom Accessibility Policy](./gar-page-zoom-policy.md)
@@ -0,0 +1,144 @@
+# Chromium DevTools Console Policy
+
+[goo.gle/devtools-console-policy](http://goo.gle/devtools-console-policy)
+([go/chrome-devtools:console-policy](http://go/chrome-devtools:console-policy))
+
+**TL;DR:** This policy outlines a strategy to keep the signal to noise ratio in
+the Console panel of Chromium DevTools high, by setting clear expectations for
+Chromium teams what kind of information is presented to web developers via the
+Console and how it is presented. Console spam, specifically from Chromium
+itself, is a known pain point for developers (e.g.
+[crbug/338403584](http://crbug.com/338403584)).
+
+## Background
+
+The [Console panel](https://developer.chrome.com/docs/devtools/console) in the
+Chromium Developer Tools is usually the first place where web developers check
+in case something is not working as expected, and ideally they would come across
+an error or warning message here that helps them to quickly resolve the issue at
+hand. The panel shows all the messages that are logged by the web application
+but also the browser (potentially on behalf of the web application, for example
+logging uncaught exceptions).
+
+In order for it to remain useful to web developers, the signal to noise ratio
+must be as high as possible, and it’s crucially important to keep in mind that
+the information shown is (a) relevant to what the developer is looking for right
+now and (b) actionable wrt. to the issue at hand. Putting it the other way
+around, while the developer is focused on investigating a concrete problem it
+doesn’t help to show a lot of messages around potential issues, suggested
+improvements, or things that went wrong without any useful breadcrumbs (prime
+examples here are error messages from somewhere deep in Blink which contain no
+stack traces and basically just repeat the information that is already present
+on a JavaScript exception throw at the same time).
+
+## Common problems
+
+### Useless anchor
+
+A common problem we’ve observed is console messages from Chromium without a
+meaningful and actionable stack trace. Consider the following example, where the
+location attached to the console message is the first line of the main document.
+The inexperienced web developer will probably be puzzled how come
+`<!doctype html>` activates fingerprinting protection on the current page.
+
+![](./images/console-policy1.png "Useless message anchors")
+
+### For your information
+
+From a Chromium team working on a specific feature, it might be totally
+reasonable to _”let the developer know what’s going on”_, because something
+could break. But from a user’s perspective, messages that basically only convey
+non-actionable information and aren’t relevant in the context of the problem
+that the developer is investigating are useless at best. Consider the following
+example:
+
+![](./images/console-policy2.png "Confusing FYI messages")
+
+The first warning message says that Fingerprinting protection is active, but
+doesn’t tell the developer whether that’s a problem or not, and what they can do
+about it. It’s highly confusing. The second warning message states that two
+third-party cookies were blocked, but also leaves the developer wondering if
+that’s something to be concerned about or caused any actual problem.
+
+Similar messages that fall into this bucket:
+
+* `Third-party cookie will be blocked. Learn more in the Issues tab`
+* `[Violation] 'setTimeout' handler took <N>ms`
+* `[Violation] Added non-passive event listener to a scroll-blocking <some> event. Consider marking event handler as 'passive' to make the page more responsive. See <URL>`
+* `Specifying 'overflow: visible' on img, video and canvas tags may cause them to produce visual content outside of the element bounds. See https://github.com/WICG/view-transitions/blob/main/debugging_overflow_on_images.md for details.`
+
+Logging a message to the Console panel just to tell the developer to open
+another panel or read some article is specifically annoying, and over time will
+result in training web developers on ignoring messages produced by Chromium
+itself.
+
+### Repetition
+
+Repeating the same message over and over again (independent of whether it’s
+actionable and meaningful) is another source of problems:
+
+![](./images/console-policy3.png "Repeated console messages")
+
+DevTools has a feature to group similar messages, which most users have enabled,
+so the pain they feel from a lot of repeated information is manageable. But that
+also gives rise to a new problem: Problems might be hidden through the grouping
+feature outside of the viewport, because the grouping somewhat breaks the
+chronological order.
+
+## Best practice
+
+Specifically for the purpose of being able to present developers with actionable
+information, coupled with traces of data that are relevant to the issue, we’ve
+introduced the [Issues panel], and as part of
+[crbug/40173406](http://crbug.com/40173406) and related bugs already migrated a
+few spammy console messages to issues.
+
+In general, reserve the use of `context->AddConsoleMessage(...)` and similar
+APIs for rare cases when the console message adds significant value, favor a
+well-worded and helpful issue over a console message, and specifically don’t
+spit out a console message when you are already raising an exception (exceptions
+can be coupled with issues internally to provide more actionable information).
+
+## Building empathy
+
+Many Chromies might not be able to immediately relate to the struggles of web
+developers, and might not have first hand experience with sifting through
+endless logs of useless information produced by frameworks, libraries, and
+eventually the browser. But imagine the following scenario: You are using `gdb`
+or `lldb` and instead of helping you diagnose the crash somewhere deep in your
+C++ code for Autofill in the browser process, it’s spamming you with pages of
+potential performance improvements in the renderer code for `<canvas>` elements.
+At best that would be very confusing, but more likely you’d be very frustrated
+with the tool after a while. This is exactly what happens if we spam web
+developers with potential performance issues.
+
+We have a [logging policy for Chromium] to prevent ourselves from being
+overwhelmed by log messages from other Chromium teams, for the same reason.
+
+## GTM strategy
+
+The most common cause for spammy console messages from Chromium is an
+insufficient Go-To-Market (GTM) strategy for features or (potentially breaking)
+changes when it comes to developer adoption. Oftentimes it’s unclear what
+exactly the expectations are and what are the critical user journeys that web
+developers go through. Spending a bit more time on this aspect and involving
+DevRel early on can help to shine light on the matter and avoid sprinkling log
+messages all over the place to _”raise awareness”_. Specifically consider:
+
+- The precise target audience for your information, because not all web
+  developers are equal at all times.
+- Under which exact circumstances that piece of information is required.
+- Is it a nice to have (e.g. _”X could be faster if you did Y”_ or _”using A
+  poses a potential security risk for your users”_) or a critically important
+  piece of information (e.g. _”X will stop working in the next release unless
+  you do Y”_).
+
+Feel free to reach out to [devtools-dev@chromium.org] with questions, and ping
+[dsv@chromium.org](mailto:dsv@chromium.org) (Chrome DevTools TL) or
+[hablich@chromium.org](mailto:hablich@chromium.org) (Chrome DevTools PM)
+directly (specifically in case of code reviews which add new problematic console
+messages).
+
+  [Issues panel]: https://developer.chrome.com/docs/devtools/issues
+  [logging policy for Chromium]: https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++.md#logging
+  [devtools-dev@chromium.org]: https://groups.google.com/a/chromium.org/g/devtools-dev