Skip to content

docs: warn about dictConfig clearing OTel handlers in logs example #5420

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

Closed
avinab-neogy wants to merge 2 commits into from
+23 −0
Closed

docs: warn about dictConfig clearing OTel handlers in logs example #5420

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e8465b0
docs: warn about dictConfig clearing OTel handlers in logs example
avinab-neogy Jul 16, 2026
67620ef
add changelog fragment for #5420
avinab-neogy Jul 16, 2026
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
1 change: 1 addition & 0 deletions .changelog/5420.changed
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
docs: warn about `dictConfig` clearing OTel handlers in logs example
22 changes: 22 additions & 0 deletions docs/examples/logs/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,28 @@ The source files of these examples are available :scm_web:`here <docs/examples/l
``opentelemetry-instrumentation-logging`` package in the contrib repo
and is deprecated in ``opentelemetry-sdk``.

.. warning::
If you configure logging using ``logging.config.dictConfig``, be aware
that it may clear existing handlers on the root logger, including the
OTel handler. To avoid losing telemetry, save and restore the root
logger handlers around the ``dictConfig`` call:

@DylanRussell DylanRussell Jul 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This is incorrect, the opposite is true. We explicitly preserve the handler by removing it before logging.config.dictConfig and logging.config.fileConfig are called, and then re-adding it back after, see

https://github.com/open-telemetry/opentelemetry-python-contrib/blob/79f9e575e96199ece9ee79d79e25adaf8cbc52f2/instrumentation/opentelemetry-instrumentation-logging/src/opentelemetry/instrumentation/logging/handler.py#L42-L79

https://github.com/open-telemetry/opentelemetry-python-contrib/blob/79f9e575e96199ece9ee79d79e25adaf8cbc52f2/instrumentation/opentelemetry-instrumentation-logging/tests/test_handler.py#L675-L717

@avinab-neogy avinab-neogy Jul 17, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

@DylanRussell @herin049 Thanks for pointing that out, you're both totally right!

To answer your question @herin049, I went back into my local setup and my original test was just running standard Python's dictConfig function with a vanilla StreamHandler, completely bypassing the OTel instrumentation.

I tested it again using the OpenTelemetry library, and I could see how it automatically saves and restores the handler.

import logging
import logging.config
from opentelemetry.instrumentation.logging import LoggingInstrumentor

LoggingInstrumentor().instrument()
root_logger = logging.getLogger()

print('Before dictConfig:', root_logger.handlers) # [<LoggingHandler (NOTSET)>]

logging.config.dictConfig({'version': 1, 'root': {'level': 'DEBUG', 'handlers': []}})

print('After dictConfig: ', root_logger.handlers) # [<LoggingHandler (NOTSET)>] - It does not get cleared!

That said, I originally opened this to address Point 3 from Issue #4738 :

  1. the root logger is instrumented, so handlers on it must not be cleared and if you are loading logging settings with logging/.config.dictConfig, you must save the root loggers before applying dictConfig, then re-apply missing handlers

This issue explicitly asked for this warning to be added to the docs. I'm guessing that requirement came from someone configuring the LoggingHandler manually via the core SDK, where this monkey-patch doesn't exist?

How would you prefer to handle this? I'm happy to do either of the following:

  1. Close this PR, and we can update Point 3 on the original issue to say it's no longer an issue when using the instrumentation library.
  2. Keep the PR open but rewrite the warning to clarify that it only applies when configuring the LoggingHandler manually via the core SDK, since dictConfig will still clear their handlers without the instrumentation package.

@herin049 herin049 Jul 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I think we should just close this PR, I don't see any behavior here that needs to be documented.

@avinab-neogy avinab-neogy Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Sounds good! Closing this PR out. Thanks for the review and for clearing this up!

.. code-block:: python

import logging
import logging.config

# Save OTel handlers before calling dictConfig
otel_handlers = logging.getLogger().handlers[:]

logging.config.dictConfig({
"version": 1,
"root": {"level": "DEBUG"},
})

# Re-apply saved handlers
for handler in otel_handlers:
logging.getLogger().addHandler(handler)

Installation
------------
Expand Down
Loading