Replace `debug` configuration setting with `loglevel`

CHANGES.md

@@ -23,6 +23,8 @@
 
 ### Breaking changes
 
+- The ``debug`` configuration option has been replaced with [loglevel](https://conversejs.org/docs/html/configuration.html#loglevel).
+
 - In contrast to sessionStorage and localStorage, IndexedDB is an asynchronous database.
   A lot of code that relied on database access to be synchronous had to be
   updated to work with asynchronous access via promises.

docs/source/configuration.rst

@@ -625,16 +625,15 @@ a chat state indication of ``active`` will be sent out.
 
 A value of ``0`` means that this feature is disabled.
 
-.. _`debug`:
+.. _`loglevel`:
 
-debug
------
-
-* Default:  ``false``
+loglevel
+--------
 
-If set to ``true``, debugging output will be logged to the browser console.
+* Default:  ``'info'``
+* Allowed values: ``'debug'``, ``'info'``, ``'warn'``, ``'error'``, ``'fatal'``
 
-You can also set this value by changing the URL fragment to `#converse?debug=true` or `#converse?debug=false`.
+You can also set this value by changing a URL fragment `#converse?loglevel=debug`
 
 
 default_domain

docs/source/troubleshooting.rst

@@ -12,7 +12,7 @@ General tips on debugging Converse
 Enabling debug output
 ---------------------
 
-Converse has a :ref:`debug` configuration setting which lets you to turn on
+Converse has a :ref:`loglevel` configuration setting which lets you to turn on
 debug logging in the browser's developer console.
 
 When debugging, you always want to make sure that this setting is set to
@@ -21,18 +21,18 @@ When debugging, you always want to make sure that this setting is set to
 You can also enable debug output via the URL, which is useful when you don't
 have access to the server where Converse is hosted.
 
-To do so, add ``#converse?debug=true`` to the URL in the browser's address bar.
+To do so, add ``#converse?loglevel=debug`` to the URL in the browser's address bar.
 Make sure to first remove any already existing URL fragment (the URL fragment
 is the part that starts with a ``#``).
 
-With debug mode on, you can open the browser's developer console and study the
+With debug logging on, you can open the browser's developer console and study the
 data that is logged to it.
 
 In Chrome you can right click in the developer console and save its contents to
 a file for later study.
 
-What is logged in debug mode?
------------------------------
+What is logged at the debug loglevel?
+-------------------------------------
 
 `Strope.js <http://strophe.im/>`_, the underlying XMPP library which Converse
 uses, swallows errors so that messaging can continue in cases where
@@ -50,7 +50,7 @@ Additionally, Converse will in debug mode also log all XMPP stanzas
 This is very useful for debugging issues relating to the XMPP protocol.
 
 For example, if a message or presence update doesn't appear, one of the first
-things you can do is to set ``debug: true`` and then to check in the console
+things you can do is to set ``loglevel: debug`` and then to check in the console
 whether the relevant XMPP stanzas are actually logged (which would mean that
 they were received by Converse). If they're not logged, then the problem is
 more likely on the XMPP server's end (perhaps a misconfiguration?). If they

src/converse-omemo.js

@@ -306,7 +306,7 @@ converse.plugins.add('converse-omemo', {
             },
 
             reportDecryptionError (e) {
-                if (_converse.debug) {
+                if (_converse.loglevel === 'debug') {
                     const { __ } = _converse;
                     this.messages.create({
                         'message': __("Sorry, could not decrypt a received OMEMO message due to an error.") + ` ${e.name} ${e.message}`,

src/headless/converse-chat.js

@@ -146,7 +146,7 @@ converse.plugins.add('converse-chat', {
             getMessageText () {
                 if (this.get('is_encrypted')) {
                     return this.get('plaintext') ||
-                           (_converse.debug ? __('Unencryptable OMEMO message') : null);
+                           (_converse.loglevel === 'debug' ? __('Unencryptable OMEMO message') : null);
                 }
                 return this.get('message');
             },

src/headless/converse-core.js

@@ -252,7 +252,7 @@ _converse.default_settings = {
     connection_options: {},
     credentials_url: null, // URL from where login credentials can be fetched
     csi_waiting_time: 0, // Support for XEP-0352. Seconds before client is considered idle and CSI is sent out.
-    debug: false,
+    loglevel: 'info',
     default_state: 'online',
     discover_connection_methods: false,
     geouri_regex: /https\:\/\/www.openstreetmap.org\/.*#map=[0-9]+\/([\-0-9.]+)\/([\-0-9.]+)\S*/g,
@@ -280,13 +280,6 @@ _converse.default_settings = {
     whitelisted_plugins: []
 };
 
-const loglevel = _converse.debug ? Strophe.LogLevel.DEBUG : Strophe.LogLevel.INFO;
-log.initialize(loglevel);
-_converse.log = log.log;
-
-Strophe.log = function (level, msg) { log.log(level+' '+msg, level); };
-Strophe.error = function (msg) { log.log(msg, Strophe.LogLevel.ERROR); };
-
 
 /**
  * Translate the given string based on the current locale.
@@ -822,19 +815,18 @@ async function onConnected (reconnecting) {
 
 
 function setUpXMLLogging () {
-    Strophe.log = function (level, msg) {
-        log.log(msg, level);
-    };
-    _converse.connection.xmlInput = function (body) {
-        if (_converse.debug) {
-            log.log(body.outerHTML, Strophe.LogLevel.DEBUG, 'color: darkgoldenrod');
-        }
-    };
-    _converse.connection.xmlOutput = function (body) {
-        if (_converse.debug) {
-            log.log(body.outerHTML, Strophe.LogLevel.DEBUG, 'color: darkcyan');
-        }
-    };
+    const lmap = {}
+    lmap[Strophe.LogLevel.DEBUG] = 'debug';
+    lmap[Strophe.LogLevel.INFO] = 'info';
+    lmap[Strophe.LogLevel.WARN] = 'warn';
+    lmap[Strophe.LogLevel.ERROR] = 'error';
+    lmap[Strophe.LogLevel.FATAL] = 'fatal';
+
+    Strophe.log = (level, msg) => log.log(msg, lmap[level]);
+    Strophe.error = (msg) => log.error(msg);
+
+    _converse.connection.xmlInput = body => log.debug(body.outerHTML, 'color: darkgoldenrod');
+    _converse.connection.xmlOutput = body => log.debug(body.outerHTML, 'color: darkcyan');
 }
 
 
@@ -985,6 +977,9 @@ _converse.initialize = async function (settings, callback) {
     this.settings = {};
     _.assignIn(this.settings, _.pick(settings, Object.keys(this.default_settings)));
 
+    log.setLogLevel(_converse.loglevel);
+    _converse.log = log.log;
+
     if (this.authentication === _converse.ANONYMOUS) {
         if (this.auto_login && !this.jid) {
             throw new Error("Config Error: you need to provide the server's " +
@@ -993,13 +988,10 @@ _converse.initialize = async function (settings, callback) {
         }
     }
 
-    _converse.router.route(/^converse\?debug=(true|false)$/, 'debug', debug => {
-        if (debug === 'true') {
-            _converse.debug = true;
-        } else {
-            _converse.debug = false;
-        }
-    });
+    _converse.router.route(
+        /^converse\?loglevel=(debug|info|warn|error|fatal)$/, 'loglevel',
+        l => log.setLogLevel(l)
+    );
 
     /* Localisation */
     if (i18n === undefined || _converse.isTestEnv()) {

src/headless/log.js

-import * as strophe from 'strophe.js/src/core';
 import { get, isElement } from 'lodash';
 
-const Strophe = strophe.default.Strophe;
 
 const logger = Object.assign({
     'debug': get(console, 'log') ? console.log.bind(console) : function noop () {},
@@ -18,13 +16,15 @@ const logger = Object.assign({
 const log = {
 
     /**
-     * Initialize the logger by setting the loglevel
-     * @method log#initialize
-     * @param { string } message - The message to be logged
+     * The the log-level, which determines how verbose the logging is.
+     * @method log#setLogLevel
      * @param { integer } level - The loglevel which allows for filtering of log messages
      */
-    initialize (loglevel) {
-        this.loglevel = loglevel;
+    setLogLevel(level) {
+        if (!['debug', 'info', 'warn', 'error', 'fatal'].includes(level)) {
+            throw new Error(`Invalid loglevel: ${level}`);
+        }
+        this.loglevel = level;
     },
 
     /**
@@ -38,9 +38,9 @@ const log = {
      * @param { integer } level - The loglevel which allows for filtering of log messages
      */
     log (message, level, style='') {
-        if (level === Strophe.LogLevel.ERROR || level === Strophe.LogLevel.FATAL) {
+        if (level === 'error' || level === 'fatal') {
             style = style || 'color: maroon';
-        } else if (level === Strophe.LogLevel.DEBUG) {
+        } else if (level === 'debug') {
             style = style || 'color: green';
         }
 
@@ -50,37 +50,39 @@ const log = {
             message = message.outerHTML;
         }
         const prefix = style ? '%c' : '';
-        if (level === Strophe.LogLevel.ERROR) {
+        if (level === 'error') {
             logger.error(`${prefix} ERROR: ${message}`, style);
-        } else if (level === Strophe.LogLevel.WARN) {
+        } else if (level === 'warn') {
             logger.warn(`${prefix} ${(new Date()).toISOString()} WARNING: ${message}`, style);
-        } else if (level === Strophe.LogLevel.FATAL) {
+        } else if (level === 'fatal') {
             logger.error(`${prefix} FATAL: ${message}`, style);
-        } else if (this.loglevel === Strophe.LogLevel.DEBUG && level === Strophe.LogLevel.DEBUG) {
-            logger.debug(`${prefix} ${(new Date()).toISOString()} DEBUG: ${message}`, style);
-        } else if (this.loglevel === Strophe.LogLevel.INFO) {
+        } else if (level === 'debug') {
+            if (this.loglevel === 'debug') {
+                logger.debug(`${prefix} ${(new Date()).toISOString()} DEBUG: ${message}`, style);
+            }
+        } else if (this.loglevel === 'info') {
             logger.info(`${prefix} ${(new Date()).toISOString()} INFO: ${message}`, style);
         }
     },
 
-    debug (message) {
-        this.log(message, Strophe.LogLevel.DEBUG);
+    debug (message, style) {
+        this.log(message, 'debug', style);
     },
 
-    error (message) {
-        this.log(message, Strophe.LogLevel.ERROR);
+    error (message, style) {
+        this.log(message, 'error', style);
     },
 
-    info (message) {
-        this.log(message, Strophe.LogLevel.INFO);
+    info (message, style) {
+        this.log(message, 'info', style);
     },
 
-    warn (message) {
-        this.log(message, Strophe.LogLevel.WARN);
+    warn (message, style) {
+        this.log(message, 'warn', style);
     },
 
-    fatal (message) {
-        this.log(message, Strophe.LogLevel.FATAL);
+    fatal (message, style) {
+        this.log(message, 'fatal', style);
     }
 }
 

tests/mock.js

@@ -228,7 +228,7 @@
             'animate': false,
             'auto_subscribe': false,
             'bosh_service_url': 'montague.lit/http-bind',
-            'debug': false,
+            'loglevel': 'warn',
             'i18n': 'en',
             'no_trimming': true,
             'play_sounds': false,