From 2c3ed415a9cd59a0d4e7f438017082e44aed465c Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Fri, 13 May 2022 12:46:10 +0100 Subject: [PATCH 1/3] docs: document the logging_config trait --- docs/source/conf.py | 1 + docs/source/operators/configuring-logging.rst | 143 ++++++++++++++++++ docs/source/operators/index.rst | 1 + pyproject.toml | 2 +- 4 files changed, 146 insertions(+), 1 deletion(-) create mode 100644 docs/source/operators/configuring-logging.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index 32951458f4..00a0612f34 100644 --- a/docs/source/conf.py +++ b/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), diff --git a/docs/source/operators/configuring-logging.rst b/docs/source/operators/configuring-logging.rst new file mode 100644 index 0000000000..ba68cdb6ef --- /dev/null +++ b/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', + }, + }, diff --git a/docs/source/operators/index.rst b/docs/source/operators/index.rst index 41354bce73..846aa2cd05 100644 --- a/docs/source/operators/index.rst +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 38a4f3fc99..49aaf4ebfa 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -42,7 +42,7 @@ dependencies = [ "Send2Trash", "terminado>=0.8.3", "tornado>=6.2.0", - "traitlets>=5.1", + "traitlets>=5.2.1", "websocket-client", "jupyter_events>=0.4.0" ] From 2bb8810a671f8ea180b7ebd0da4d4294a4352008 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 15 Nov 2022 12:06:12 +0000 Subject: [PATCH 2/3] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 00a0612f34..03649e1cc7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -358,7 +358,7 @@ # texinfo_no_detailmenu = False intersphinx_mapping = { - 'python': ('https://docs.python.org/', None), + "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), From 884a47a79293224bba9f88d8072874d184796194 Mon Sep 17 00:00:00 2001 From: Steven Silvester Date: Tue, 15 Nov 2022 08:15:16 -0600 Subject: [PATCH 3/3] increase bump --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 49aaf4ebfa..5e286213aa 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -42,7 +42,7 @@ dependencies = [ "Send2Trash", "terminado>=0.8.3", "tornado>=6.2.0", - "traitlets>=5.2.1", + "traitlets>=5.3.0", "websocket-client", "jupyter_events>=0.4.0" ]