diff --git a/CHANGES.md b/CHANGES.md index 2034c8b5f..ad2e96f9a 100644 --- a/CHANGES.md +++ b/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. diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index d9b7ae515..6d161273d 100644 --- a/docs/source/configuration.rst +++ b/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 ------ +loglevel +-------- -* Default: ``false`` +* Default: ``'info'`` +* Allowed values: ``'debug'``, ``'info'``, ``'warn'``, ``'error'``, ``'fatal'`` -If set to ``true``, debugging output will be logged to the browser console. - -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 diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 830e3f262..496e0d5bf 100644 --- a/docs/source/troubleshooting.rst +++ b/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 `_, 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 diff --git a/src/converse-omemo.js b/src/converse-omemo.js index 7e70b6e7a..b75bd93db 100644 --- a/src/converse-omemo.js +++ b/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}`, diff --git a/src/headless/converse-chat.js b/src/headless/converse-chat.js index 096f2566e..8b421e2ff 100644 --- a/src/headless/converse-chat.js +++ b/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'); }, diff --git a/src/headless/converse-core.js b/src/headless/converse-core.js index eed3cc6aa..1740c5a3b 100644 --- a/src/headless/converse-core.js +++ b/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()) { diff --git a/src/headless/log.js b/src/headless/log.js index a350fcaf8..7d8493bce 100644 --- a/src/headless/log.js +++ b/src/headless/log.js @@ -1,7 +1,5 @@ -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); } } diff --git a/tests/mock.js b/tests/mock.js index 354a3ec70..9564ce30e 100644 --- a/tests/mock.js +++ b/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,