Repository navigation
Clarify when logging events are propagated when propagate is true #80002
Description
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = <Date 2021-12-07.11:46:07.117>
created_at = <Date 2019-01-24.20:07:19.203>
labels = ['type-feature', '3.7', 'docs']
title = 'Clarify when logging events are propagated when propagate is true'
updated_at = <Date 2021-12-07.15:48:42.051>
user = 'https://github.com/cjerdonek'bugs.python.org fields:
activity = <Date 2021-12-07.15:48:42.051>
actor = 'miss-islington'
assignee = 'docs@python'
closed = True
closed_date = <Date 2021-12-07.11:46:07.117>
closer = 'vinay.sajip'
components = ['Documentation']
creation = <Date 2019-01-24.20:07:19.203>
creator = 'chris.jerdonek'
dependencies = []
files = []
hgrepos = []
issue_num = 35821
keywords = ['patch']
message_count = 13.0
messages = ['334320', '334333', '334340', '334342', '334360', '334362', '334503', '407914', '407919', '407920', '407943', '407944', '407945']
nosy_count = 6.0
nosy_names = ['vinay.sajip', 'chris.jerdonek', 'docs@python', 'miss-islington', 'xtreak', 'kj']
pr_nums = ['29841', '29957', '29958', '29963', '29965', '29966']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue35821'
versions = ['Python 3.7']
Activity
cjerdonek commentedon Jan 24, 2019
Currently, the logging docs are a bit ambiguous or at least not completely clear as to when events are propagated when Logger.propagate is true. The docs currently say 1--
"If [the
propagate] attribute evaluates to true, events logged to this logger will be passed to the handlers of higher level (ancestor) loggers, in addition to any handlers attached to this logger."But it's not clear if "logged to this logger" means (1) a log method like info() or error() was called on the logger, or (2) the event was passed to the logger's handlers (i.e. satisfied the logger's log level threshold and any filters).
Empirically, I found that the meaning is (2).
cjerdonek commentedon Jan 25, 2019
Also, does "logged to this logger" include events propagated to it from a child logger? For example, if an event is logged to logger "A.B.C" and propagated to "A.B", will the propagate attribute of the latter effect whether logger "A" (or its handlers) sees it?
vsajip commentedon Jan 25, 2019
I believe the information is clear from this link in the documentation:
https://docs.python.org/3/howto/logging.html#logging-flow
However, if you can suggest alternative wording which you think is clearer, I'll certainly take a look at it. Perhaps a link could be added to this section from the logging.Logger.propagate section.
cjerdonek commentedon Jan 25, 2019
Thanks for the diagram. How about the following as a replacement?
"If this attribute is true and the event isn't rejected by the logger's level and filters, an event passed to this logger will recursively be passed to its parent logger and handled by the parent logger's handlers (after being handled by the original logger's handlers). The logger level and filters only come into play for the very first logger in this chain. For subsequent loggers, only the propagate attribute determines whether the event is passed to the parent."
vsajip commentedon Jan 25, 2019
That isn't quite accurate. A logger's attached handlers will always be offered a chance to handle an event if the logger's level and filters allow. However, the event is not actually passed to ancestor loggers - it is directly offered to any handlers attached to ancestor loggers, until a logger is encountered where propagate is false - and that is the last logger whose handlers are offered the event. All handlers have their own levels and filters and may or may not process an event according to those levels and filters.
cjerdonek commentedon Jan 25, 2019
I'm not sure which part of what I wrote you think is inaccurate. All of what you wrote matches what I was trying to convey.
For example, my saying "pass to the parent logger" corresponds to the "set current logger to parent" box in the diagram. And by "handled by the parent logger's handlers" I meant "directly offered to any handlers attached to ancestor loggers." And "only the propagate attribute determines whether the event is passed" matches your "until a logger is encountered where propagate is false."
vsajip commentedon Jan 29, 2019
It's just that language can be tricky. When you said "pass to the parent logger" this might be misconstrued as some kind of call to a method of the parent logger.
Your OP says that you think "logged to this logger" means (2), but actually it means (1). Expanding with examples:
If the propagate attribute of the logger named A.B.C evaluates to true, any event logged to A.B.C via a method call such as logging.getLogger('A.B.C').error(...) will [subject to passing that logger's level and filter settings] be passed in turn to any handlers attached to loggers named A.B, A and the root logger, after first being passed to any handlers attached to A.B.C. If any logger in the chain A.B.C, A.B, A has its propagate attribute set to false, then that is the last logger whose handlers are offered the event to handle, and propagation stops at that point.
vsajip commentedon Dec 7, 2021
New changeset 2bf5517 by Vinay Sajip in branch 'main':
bpo-35821: Add an example to Logger.propagate documentation. (GH-29841)
2bf5517
vsajip commentedon Dec 7, 2021
New changeset f78c229 by Miss Islington (bot) in branch '3.10':
[3.10] bpo-35821: Add an example to Logger.propagate documentation. (GH-29841) (GH-29957)
f78c229
vsajip commentedon Dec 7, 2021
New changeset e688568 by Miss Islington (bot) in branch '3.9':
[3.9] bpo-35821: Add an example to Logger.propagate documentation. (GH-29841) (GH-29958)
e688568
Fidget-Spinner commentedon Dec 7, 2021
New changeset c7e7a4b by Ken Jin in branch 'main':
bpo-35821: Fix restructuredtext code formatting in logging.rst (GH-29963)
c7e7a4b
miss-islington commentedon Dec 7, 2021
New changeset 14f03ce by Miss Islington (bot) in branch '3.10':
[3.10] bpo-35821: Fix restructuredtext code formatting in logging.rst (GH-29963) (GH-29965)
14f03ce
miss-islington commentedon Dec 7, 2021
New changeset db42809 by Miss Islington (bot) in branch '3.9':
bpo-35821: Fix restructuredtext code formatting in logging.rst (GH-29963)
db42809