toolkit/docs/javascript-logging.md

   1 # JavaScript Logging
   2
   3 This document details logging in JavaScript. For c++ based logging, please see
   4 the [Gecko Logging document](/xpcom/logging).
   5
   6 ## Notes About Logging
   7
   8 ### Logging Ethos
   9
  10 The general ethos is to keep the browser console "clean" of logging output by
  11 default, except in situations where there are errors or potentially warnings.
  12
  13 There is also [a test](https://searchfox.org/mozilla-central/source/browser/components/tests/marionette/test_no_errors_clean_profile.py)
  14 which will fail if there are any unexpected logs on startup.
  15
  16 For situations where it is useful to have debug logging available, these are
  17 generally covered by off-by-default logging which can be enabled by a preference.
  18
  19 Also be aware that console logging can have a performance impact even when the
  20 developer tools are not displayed.
  21
  22 ### Obsolete Utilities
  23
  24 In the tree, there are two modules that should be considered obsolete:
  25 [Log.sys.mjs](https://searchfox.org/mozilla-central/source/toolkit/modules/Log.sys.mjs)
  26 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
  27 the [one logger](https://bugzilla.mozilla.org/show_bug.cgi?id=881389) effort.
  28
  29 The `console` object is available in all areas of the Firefox code base and
  30 has better integration into the developer tools than the existing modules.
  31
  32 ## Logging using the Console Web API
  33
  34 The [Console Web API](https://developer.mozilla.org/docs/Web/API/console)
  35 is available throughout the Firefox code base. It is the best tool to use, as it
  36 integrates directly with the
  37 [developer tools](/devtools-user/index), which
  38 provide detailed logging facilities.
  39
  40 By default logs will be output to the browser console, according to the processes
  41 and filters selected within the console itself.
  42
  43 Logs may also be output to stdout via the `devtools.console.stdout.chrome` preference.
  44 By default, this is set to true for non-official builds, and false for official builds,
  45 meaning most of the time, developers do not need to change it.
  46
  47 ### console.createInstance
  48
  49 In some cases, it is useful to attribute logging to a particular module or have
  50 it controlled by a preference. In this case, `console.createInstance` may be used
  51 to create a specific logging instance.
  52
  53 For example:
  54
  55 ```js
  56 const lazy = {};
  57
  58 ChromeUtils.defineLazyGetter(lazy, "logConsole", () => {
  59   return console.createInstance({
  60     maxLogLevelPref: "browser.download.loglevel",
  61     prefix: "Downloads",
  62   });
  63 });
  64 ```
  65
  66 The preference might have a typical default value of `Error`. The available
  67 levels are listed in [Console.webidl](https://searchfox.org/mozilla-central/rev/593c49fa812ceb4be45fcea7c9e90d15f59edb70/dom/webidl/Console.webidl#205-209).
  68
  69 This creates a lazily initialized console instance that can be used as follows:
  70
  71 ```js
  72 // Logs by default.
  73 lazy.logConsole.error("Something bad happened");
  74
  75 // Doesn't log unless the preference was changed prior to logging.
  76 lazy.logConsole.debug("foo", 123)
  77 ```
  78
  79 ### Other Options to console.createInstance
  80
  81 `console.createInstance` may be passed other options. See
  82 [`ConsoleInstanceOptions` in the Web IDL for more details](https://searchfox.org/mozilla-central/rev/593c49fa812ceb4be45fcea7c9e90d15f59edb70/dom/webidl/Console.webidl#211-235)
  83
  84 The most useful of these is probably `maxLogLevel` which allows manually setting
  85 the log level, which may be useful for transitioning to `console.createInstance`
  86 from other logging systems where preferences already exist.