docs: warn about dictConfig clearing OTel handlers in logs example

[avinab-neogy]

Description

Follow-up to #5344 which addressed the LoggingHandler move to contrib.

Refs #4738

This PR documents the dictConfig handler-saving pattern from point 3
of #4738. When dictConfig is called with a root section that defines
handlers, it clears existing handlers on the root logger including the
OTel handler, silently breaking telemetry. Users need to save and
restore handlers around the call.

Tested locally — confirmed that dictConfig with a root section wipes
all existing handlers.

Opening as draft to confirm scope before requesting review.
@xrmx does this belong in the logs example README or somewhere else?

Type of change

• This change requires a documentation update

How Has This Been Tested?

Verified locally that calling dictConfig with a root section clears
existing handlers:

import logging, logging.config
handler = logging.StreamHandler()
logging.getLogger().addHandler(handler)
print('Before:', logging.getLogger().handlers)  # [StreamHandler]
logging.config.dictConfig({'version': 1, 'root': {'level': 'DEBUG', 'handlers': []}})
print('After:', logging.getLogger().handlers)   # []

Does This PR Require a Contrib Repo Change?

• No.

Checklist:

• Followed the style guidelines of this project
• Changelogs have been updated
• Unit tests have been added
• Documentation has been updated

[DylanRussell]

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]

@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 :

3. 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]

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

[herin049]

I have the same understanding as @DylanRussell. Do you have an example reproduction that actually involves using the logging instrumentation library?