From 79a545ed0a7169e8b4e460f4ba760a449745bcf2 Mon Sep 17 00:00:00 2001 From: dgw Date: Wed, 29 Nov 2023 11:59:21 -0600 Subject: [PATCH 1/3] docs: clarify logging config overview There is always a log format and a log date format because those options in the core section have defaults. Likewise, the default logging level of INFO exists even if not set explicitly by the config file. (Removed the confusing bit about WARNING being the default; that's the default of the `level` argument to `logging.basicConfig()`, but Sopel always passes the value of its `logging_level` setting.) --- docs/source/run/configuration.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/source/run/configuration.rst b/docs/source/run/configuration.rst index 33d0e3282..52151cc8e 100644 --- a/docs/source/run/configuration.rst +++ b/docs/source/run/configuration.rst @@ -804,12 +804,10 @@ there may be as many as four log files per config: Sopel uses the built-in :func:`logging.basicConfig` function to configure its logs with the following arguments: -* ``format``: set to :attr:`~CoreSection.logging_format` if configured -* ``datefmt``: set to :attr:`~CoreSection.logging_datefmt` if configured -* ``level``: set to :attr:`~CoreSection.logging_level`, default to ``WARNING`` - (see the Python documentation for `available logging levels`__) - -.. __: https://docs.python.org/3/library/logging.html#logging-levels +* ``format``: set to :attr:`~CoreSection.logging_format` +* ``datefmt``: set to :attr:`~CoreSection.logging_datefmt` +* ``level``: set to :attr:`~CoreSection.logging_level` (see + :ref:`available logging levels ` in Python's documentation) Example of configuration for logging:: From 7c84903841b7d4d7b053cd9f6bb368d7222b5548 Mon Sep 17 00:00:00 2001 From: dgw Date: Wed, 29 Nov 2023 12:30:32 -0600 Subject: [PATCH 2/3] docs: FAQ entry about obtaining logs for bug reports --- docs/source/faq.rst | 69 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 67 insertions(+), 2 deletions(-) diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 12f4f749c..1ef158b2c 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -16,6 +16,9 @@ We talk about the bot's development, and we answer questions from bot owners & plugin authors as much as we can. We try to keep it as friendly as possible; sometimes we also just chat about about non-development topics. +If you're coming to IRC with a question, you can often help us help you faster +by :ref:`having your logs ready `. + All conversations are in English (except when someone swears in French). .. __: https://libera.chat/guides/connect @@ -31,10 +34,72 @@ configured some templates to help and guide you through the process and hopefully to make it easier for you. Before submitting your bug, you can `search existing issues`__ to see if there -is one open already. +is one open already. If no existing issue covers your bug, please :ref:`have log +excerpts ready ` that demonstrate the problem, if possible. -Do not hesitate to :ref:`contact us` if you are unsure about +Do not hesitate to :ref:`contact us ` if you are unsure about your bug report. .. __: https://github.com/sopel-irc/sopel/issues/new/choose .. __: https://github.com/sopel-irc/sopel/issues + + +.. _faq-logging: + +How to obtain logs? +=================== + +When requesting help, you'll probably be asked to provide logs illustrating the +problem. If you :ref:`report a bug `, the form includes a field +for "Relevant logs" that you should fill in if possible. + +By default you will find Sopel's logs in the ``~/.sopel/logs`` folder. If +:attr:`~.config.core_section.CoreSection.homedir` and/or +:attr:`~.config.core_section.CoreSection.logdir` is specified in Sopel's config +file, logs will be found in ``/path/to/homedir/logdir`` if ``logdir`` is a +relative path, or at ``/path/to/logdir`` if ``logdir`` is an absolute path. (If +Sopel is :doc:`being run as a service `, the ``logdir`` should be +an absolute path.) + +Log files' names start with :ref:`their associated config file's name +`, i.e. the :option:`--config ` +argument's value. + +There are two main log types you might be asked to provide: ``sopel`` logs and +``raw`` logs. + +Obtaining ``sopel`` logs +------------------------ + +``.sopel.log`` files contain everything Sopel does from startup to +shutdown. + +In normal operation, the ``INFO`` (default) or ``WARNING`` +:attr:`~.config.core_section.CoreSection.logging_level` is usually sufficient. +For ambiguous or particularly gnarly problems, you might be asked to enable +``DEBUG`` logging and reproduce your issue to help Sopel's developers understand +what's happening. + +Obtaining ``raw`` logs +---------------------- + +For certain problem types, a developer might ask for ``raw`` logs to examine +exactly what Sopel and the IRC server are saying to each other. + +These ``.raw.log`` files are not enabled by default. If requested +by the person helping you in our issue tracker or IRC channel, you can turn +``raw`` logs on using the :attr:`~.config.core_section.CoreSection.log_raw` +setting in your config file. + +.. warning:: + + The ``raw`` log may contain sensitive information, e.g. your bot's NickServ + account credentials, its IP address, or channel keys. + + Always check the portion of your ``raw`` log that you are sharing for + secrets, and censor any you find! + +.. seealso:: + + More information about configuring Sopel's logging is available in the + :ref:`Logging` section. From f48273b8b104cfa7275dca1083853c35a299de1b Mon Sep 17 00:00:00 2001 From: dgw Date: Wed, 29 Nov 2023 15:54:29 -0600 Subject: [PATCH 3/3] config.core_section: fix documentation of `logdir` option It is relative to the config's `homedir`, which is the config's parent folder by default but can be changed. While I was here: Added a note indicating why one might want to change the `homedir` setting, for example to match service-unit conventions. --- sopel/config/core_section.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/sopel/config/core_section.py b/sopel/config/core_section.py index 4f91cac44..c4e5e6110 100644 --- a/sopel/config/core_section.py +++ b/sopel/config/core_section.py @@ -756,8 +756,11 @@ class CoreSection(StaticSection): def homedir(self): """The directory in which various files are stored at runtime. - By default, this is the same directory as the config file. It cannot be - changed at runtime. + Specifying the ``homedir`` option is useful for e.g. :doc:`running Sopel + as a system service `. + + If not set, the config file's parent directory will be used. This value + cannot be changed at runtime. """ return self._parent.homedir @@ -824,7 +827,7 @@ def homedir(self): :default: ``logs`` If the given value is not an absolute path, it will be interpreted relative - to the directory containing the config file with which Sopel was started. + to the :attr:`homedir` of the config file with which Sopel was started. .. seealso::