docs: document the logging_config trait (#844)

* docs: document the logging_config trait

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* increase bump

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Steven Silvester <[email protected]>

Author: 3 people

docs/source/conf.py

@@ -358,6 +358,7 @@
 # texinfo_no_detailmenu = False
 
 intersphinx_mapping = {
+    "python": ("https://docs.python.org/", None),
     "ipython": ("https://ipython.readthedocs.io/en/stable/", None),
     "nbconvert": ("https://nbconvert.readthedocs.io/en/latest/", None),
     "nbformat": ("https://nbformat.readthedocs.io/en/latest/", None),

docs/source/operators/configuring-logging.rst

@@ -0,0 +1,143 @@
+.. _configurable_logging:
+
+Configuring Logging
+===================
+
+Jupyter Server (and Jupyter Server extension applications such as Jupyter Lab)
+are Traitlets applications.
+
+By default Traitlets applications log to stderr. You can configure them to log
+to other locations e.g. log files.
+
+Logging is configured via the ``logging_config`` "trait" which accepts a
+:py:func:`logging.config.dictConfig` object. For more information look for
+``Application.logging_config`` in :ref:`other-full-config`.
+
+
+Examples
+--------
+
+.. _configurable_logging.jupyter_server:
+
+Jupyter Server
+^^^^^^^^^^^^^^
+
+A minimal example which logs Jupyter Server output to a file:
+
+.. code-block:: python
+
+   c.ServerApp.logging_config = {
+       'version': 1,
+       'handlers': {
+           'logfile': {
+               'class': 'logging.FileHandler',
+               'level': 'DEBUG',
+               'filename': 'jupyter_server.log',
+           },
+       },
+       'loggers': {
+           'ServerApp': {
+               'level': 'DEBUG',
+               'handlers': ['console', 'logfile'],
+           },
+       },
+   }
+
+.. note::
+
+   To keep the default behaviour of logging to stderr ensure the ``console``
+   handler (provided by Traitlets) is included in the list of handlers.
+
+.. warning::
+
+   Be aware that the ``ServerApp`` log may contain security tokens. If
+   redirecting to log files ensure they have appropriate permissions.
+
+
+.. _configurable_logging.extension_applications:
+
+Jupyter Server Extension Applications (e.g. Jupyter Lab)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An example which logs both Jupyter Server and Jupyter Lab output to a file:
+
+.. note::
+
+   Because Jupyter Server and its extension applications are separate Traitlets
+   applications their logging must be configured separately.
+
+.. code-block:: python
+
+   c.ServerApp.logging_config = {
+       'version': 1,
+       'handlers': {
+           'logfile': {
+               'class': 'logging.FileHandler',
+               'level': 'DEBUG',
+               'filename': 'jupyter_server.log',
+               'formatter': 'my_format',
+           },
+       },
+       'formatters': {
+           'my_format': {
+               'format': '%(asctime)s %(levelname)-8s %(name)-15s %(message)s',
+               'datefmt': '%Y-%m-%d %H:%M:%S',
+           },
+       },
+       'loggers': {
+           'ServerApp': {
+               'level': 'DEBUG',
+               'handlers': ['console', 'logfile'],
+           },
+       },
+   }
+
+   c.LabApp.logging_config = {
+       'version': 1,
+       'handlers': {
+           'logfile': {
+               'class': 'logging.FileHandler',
+               'level': 'DEBUG',
+               'filename': 'jupyter_server.log',
+               'formatter': 'my_format',
+           },
+       },
+       'formatters': {
+           'my_format': {
+               'format': '%(asctime)s %(levelname)-8s %(name)-15s %(message)s',
+               'datefmt': '%Y-%m-%d %H:%M:%S',
+           },
+       },
+       'loggers': {
+           'LabApp': {
+               'level': 'DEBUG',
+               'handlers': ['console', 'logfile'],
+           },
+       },
+   }
+
+.. note::
+
+   The configured application name should match the logger name
+   e.g. ``c.LabApp.logging_config`` defines a logger called ``LabApp``.
+
+.. tip::
+
+   This diff modifies the example to log Jupyter Server and Jupyter Lab output
+   to different files:
+
+   .. code-block:: diff
+
+      --- before
+      +++ after
+       c.LabApp.logging_config = {
+           'version': 1,
+           'handlers': {
+               'logfile': {
+                   'class': 'logging.FileHandler',
+                   'level': 'DEBUG',
+      -            'filename': 'jupyter_server.log',
+      +            'filename': 'jupyter_lab.log',
+                   'formatter': 'my_format',
+               },
+           },

docs/source/operators/index.rst

@@ -13,3 +13,4 @@ These pages are targeted at people using, configuring, and/or deploying multiple
    migrate-from-nbserver
    public-server
    security
+   configuring-logging

pyproject.toml

@@ -42,7 +42,7 @@ dependencies = [
     "Send2Trash",
     "terminado>=0.8.3",
     "tornado>=6.2.0",
-    "traitlets>=5.1",
+    "traitlets>=5.3.0",
     "websocket-client",
     "jupyter_events>=0.4.0"
 ]