Skip to content

Commit

Permalink
docs: document the logging_config trait (jupyter-server#844)
Browse files Browse the repository at this point in the history
* 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]>
  • Loading branch information
3 people authored Nov 15, 2022
1 parent cf902ea commit 830c87f
Show file tree
Hide file tree
Showing 4 changed files with 146 additions and 1 deletion.
1 change: 1 addition & 0 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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),
Expand Down
143 changes: 143 additions & 0 deletions docs/source/operators/configuring-logging.rst
Original file line number Diff line number Diff line change
@@ -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',
},
},
1 change: 1 addition & 0 deletions docs/source/operators/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,4 @@ These pages are targeted at people using, configuring, and/or deploying multiple
migrate-from-nbserver
public-server
security
configuring-logging
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]
Expand Down

0 comments on commit 830c87f

Please sign in to comment.