Merge pull request #2574 from sopel-irc/faq-logs

docs: FAQ entry on logging + some minor clarification

Author: dgw

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 <faq-logging>`.
+
 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 <faq-logging>` that demonstrate the problem, if possible.
 
-Do not hesitate to :ref:`contact us<faq-contact-us>` if you are unsure about
+Do not hesitate to :ref:`contact us <faq-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 <faq-bug-report>`, 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 <run/service>`, the ``logdir`` should be
+an absolute path.)
+
+Log files' names start with :ref:`their associated config file's name
+<logging-basename>`, i.e. the :option:`--config <sopel start --config>`
+argument's value.
+
+There are two main log types you might be asked to provide: ``sopel`` logs and
+``raw`` logs.
+
+Obtaining ``sopel`` logs
+------------------------
+
+``<configname>.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 ``<configname>.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.

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 <levels>` in Python's documentation)
 
 Example of configuration for logging::
 

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 </run/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::