diff --git a/docs/source/conf.py b/docs/source/conf.py index 32951458f4..03649e1cc7 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..5e286213aa 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.3.0", "websocket-client", "jupyter_events>=0.4.0" ]