Skip to content

[doc] Update documentation on logging optimization. (GH-22075) #22075

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 3, 2020
Merged

[doc] Update documentation on logging optimization. (GH-22075) #22075

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1350126
Update documentation on logging optimization.
vsajip Sep 3, 2020
35b83d3
Refine documentation change.
vsajip Sep 3, 2020
a0e60e3
Add a cross-reference.
vsajip Sep 3, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 15 additions & 14 deletions Doc/howto/logging.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1078,20 +1078,21 @@ need more precise control over what logging information is collected. Here's a
list of things you can do to avoid processing during logging which you don't
need:

+-----------------------------------------------+----------------------------------------+
| What you don't want to collect | How to avoid collecting it |
+===============================================+========================================+
| Information about where calls were made from. | Set ``logging._srcfile`` to ``None``. |
| | This avoids calling |
| | :func:`sys._getframe`, which may help |
| | to speed up your code in environments |
| | like PyPy (which can't speed up code |
| | that uses :func:`sys._getframe`). |
+-----------------------------------------------+----------------------------------------+
| Threading information. | Set ``logging.logThreads`` to ``0``. |
+-----------------------------------------------+----------------------------------------+
| Process information. | Set ``logging.logProcesses`` to ``0``. |
+-----------------------------------------------+----------------------------------------+
+-----------------------------------------------+---------------------------------------------------+
| What you don't want to collect | How to avoid collecting it |
+===============================================+===================================================+
| Information about where calls were made from. | Set ``logging._srcfile`` to ``None``. |
| | This avoids calling :func:`sys._getframe`, which |
| | may help to speed up your code in environments |
| | like PyPy (which can't speed up code that uses |
| | :func:`sys._getframe`). |
+-----------------------------------------------+---------------------------------------------------+
| Threading information. | Set ``logging.logThreads`` to ``False``. |
+-----------------------------------------------+---------------------------------------------------+
| Process information. | Set ``logging.logProcesses`` to ``False``. |
+-----------------------------------------------+---------------------------------------------------+
| Multiprocess information. | Set ``logging.logMultiprocessing`` to ``False``. |
+-----------------------------------------------+---------------------------------------------------+
Copy link
Member

@iritkatriel iritkatriel Sep 3, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it might not be clear from this what the difference is between "process information" and "multiprocess information". We could say more precisely "process id" instead of "process information" and "process name" instead of "multiprocessing information".

But then as a reader I might wonder why they are handled separately. So how about

| Process Id | Set logging.logProcesses to False. |
+------------------------------------------------------ ...
| Process Name (requires the multiprocessing module) | Set logging.logMultiprocessing to False. |

Copy link
Member

@iritkatriel iritkatriel Sep 3, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This documentation difficulty is actually a reflection of the API being a bit clumsy. I guess it evolved into its current state, but if we were to do it from scratch we would probably do something else.

Since it's currently not documented precisely what logProcesses does, we could make "logProcesses = False" suppress both processId and processName logging.

We should leave logMultiprocessing as it is for backwards compatibility but maybe leave it undocumented?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should make any functional changes here, just documentation changes. Changing "Process information" to "Current process information" or "Current process ID" would help distinguish from the multiprocessing case.


Also note that the core logging module only includes the basic handlers. If
you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't
Expand Down