diff options
Diffstat (limited to 'toolkit/docs')
| -rw-r--r-- | toolkit/docs/index.rst | 33 | ||||
| -rw-r--r-- | toolkit/docs/javascript-logging.md | 86 |
2 files changed, 119 insertions, 0 deletions
diff --git a/toolkit/docs/index.rst b/toolkit/docs/index.rst new file mode 100644 index 0000000000..626aed2f7d --- /dev/null +++ b/toolkit/docs/index.rst @@ -0,0 +1,33 @@ +======= +Toolkit +======= + +This is the nascent documentation of the Toolkit code that is shared across Firefox, Firefox for Android and other applications. + +.. toctree:: + :maxdepth: 1 + + javascript-logging + mozapps/extensions/addon-manager/index + components/backgroundtasks/index + components/crashes/crash-manager/index + crashreporter/crashreporter/index + components/featuregates/featuregates/index + search/index + components/normandy/normandy/index + components/nimbus/docs/index + components/messaging-system/docs/index + components/pictureinpicture/pictureinpicture/index + components/prompts/prompts/index + modules/subprocess/toolkit_modules/subprocess/index + components/telemetry/index + components/glean/index + modules/toolkit_modules/index + content/toolkit_widgets/index + components/resistfingerprinting/resistfingerprinting/index + components/url-classifier/url-classifier/index + components/extensions/webextensions/index + /extensions/spellcheck/index + mozapps/update/docs/index + components/antitracking/anti-tracking/index + components/translations/index diff --git a/toolkit/docs/javascript-logging.md b/toolkit/docs/javascript-logging.md new file mode 100644 index 0000000000..520a745cfd --- /dev/null +++ b/toolkit/docs/javascript-logging.md @@ -0,0 +1,86 @@ +# JavaScript Logging + +This document details logging in JavaScript. For c++ based logging, please see +the [Gecko Logging document](/xpcom/logging). + +## Notes About Logging + +### Logging Ethos + +The general ethos is to keep the browser console "clean" of logging output by +default, except in situations where there are errors or potentially warnings. + +There is also [a test](https://searchfox.org/mozilla-central/source/browser/components/tests/marionette/test_no_errors_clean_profile.py) +which will fail if there are any unexpected logs on startup. + +For situations where it is useful to have debug logging available, these are +generally covered by off-by-default logging which can be enabled by a preference. + +Also be aware that console logging can have a performance impact even when the +developer tools are not displayed. + +### Obsolete Utilities + +In the tree, there are two modules that should be considered obsolete: +[Log.sys.mjs](https://searchfox.org/mozilla-central/source/toolkit/modules/Log.sys.mjs) +and [Console.sys.mjs](https://searchfox.org/mozilla-central/source/toolkit/modules/Console.sys.mjs). Existing uses should be transitioned to use `console.createInstance` as part of +the [one logger](https://bugzilla.mozilla.org/show_bug.cgi?id=881389) effort. + +The `console` object is available in all areas of the Firefox code base and +has better integration into the developer tools than the existing modules. + +## Logging using the Console Web API + +The [Console Web API](https://developer.mozilla.org/docs/Web/API/console) +is available throughout the Firefox code base. It is the best tool to use, as it +integrates directly with the +[developer tools](/devtools-user/index), which +provide detailed logging facilities. + +By default logs will be output to the browser console, according to the processes +and filters selected within the console itself. + +Logs may also be output to stdout via the `devtools.console.stdout.chrome` preference. +By default, this is set to true for non-official builds, and false for official builds, +meaning most of the time, developers do not need to change it. + +### console.createInstance + +In some cases, it is useful to attribute logging to a particular module or have +it controlled by a preference. In this case, `console.createInstance` may be used +to create a specific logging instance. + +For example: + +```js +const lazy = {}; + +ChromeUtils.defineLazyGetter(lazy, "logConsole", () => { + return console.createInstance({ + maxLogLevelPref: "browser.download.loglevel", + prefix: "Downloads", + }); +}); +``` + +The preference might have a typical default value of `Error`. The available +levels are listed in [Console.webidl](https://searchfox.org/mozilla-central/rev/593c49fa812ceb4be45fcea7c9e90d15f59edb70/dom/webidl/Console.webidl#205-209). + +This creates a lazily initialized console instance that can be used as follows: + +```js +// Logs by default. +lazy.logConsole.error("Something bad happened"); + +// Doesn't log unless the preference was changed prior to logging. +lazy.logConsole.debug("foo", 123) +``` + +### Other Options to console.createInstance + +`console.createInstance` may be passed other options. See +[`ConsoleInstanceOptions` in the Web IDL for more details](https://searchfox.org/mozilla-central/rev/593c49fa812ceb4be45fcea7c9e90d15f59edb70/dom/webidl/Console.webidl#211-235) + +The most useful of these is probably `maxLogLevel` which allows manually setting +the log level, which may be useful for transitioning to `console.createInstance` +from other logging systems where preferences already exist. |