feat(logs): add OTEL_LOG_LEVEL support

[grvmishra788]

Description

Fixes #1059: The OTEL_LOG_LEVEL environment variable has been defined in the SDK since the SDK was first written, but reading and applying it was never implemented.

With this change, On SDK module load, OTEL_LOG_LEVEL is read and applied to logging.getLogger("opentelemetry.sdk") - the root SDK logger. As a result, all SDK sub-modules (trace, metrics, logs, exporters) inherit the configured level. Accepted values: debug, info, warn, warning, error, critical (case-insensitive). Invalid values emit a WARNING to stderr.

What OTEL_LOG_LEVEL controls

OTEL_LOG_LEVEL is scoped to the SDK's own diagnostic output only. It does not filter OTel log records emitted by instrumented applications. This scope is:

• Specified in the SDK environment-variables spec: "Log level used by the SDK internal logger", linked to error-handling.md#self-diagnostics.
• Confirmed by SIG member srikanthccv in issue #1059: "The OTEL_LOG_LEVEL is for setting the log level for the loggers used internally by SDK not for your application logs."
• Confirmed by jeremydvoss in closed PR #4203: "OTEL_LOG_LEVEL: Exists in the SDK but unused. Speced out to be the level for the SDK's internal logger, not the LoggingHandler."

Type of change

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

• pytest opentelemetry-sdk/tests/logs/test_logs.py — all tests pass.
• TestOtelLogLevelEnvVar.test_otel_log_level_to_python_mapping_accepted_values verifies the _OTEL_LOG_LEVEL_TO_PYTHON dict covers exactly the documented accepted values: {"debug", "info", "warn", "warning", "error", "critical"}.
• Manual smoke test: set OTEL_LOG_LEVEL=debug before importing the SDK and confirm SDK debug messages appear; set OTEL_LOG_LEVEL=invalid and confirm a WARNING is emitted with the valid values listed.

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

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: grvmishra788 / name: Gaurav Mishra (100a78c, 52e069c, 8fc84d1, ebe9bc6, ff00ae5, 5283977, 7c01660, 93fcffd, a8cf853, b36d053)
• ✅ login: MikeGoldsmith / name: Mike Goldsmith (501df97)

[MikeGoldsmith]

Thanks @grvmishra788. I think we need to move this so the main sdk/__init__.py so we don't need users to import another module.

[MikeGoldsmith]

Thanks @grvmishra788 - looks really good. Just a few final tweaks for an errant new line and update to the changelog.

[grvmishra788]

Hi @MikeGoldsmith! Could you please take a look at the PR now? It has been in review for a while.

[MikeGoldsmith]

Sorry for the delay, thanks @grvmishra788 🚀

[grvmishra788]

@MikeGoldsmith One of the CI checks failed CI / contrib / sdk-extension-aws-1 (pull_request) - a completely different package (opentelemetry-sdk-extension-aws) that this PR doesn't touch. This appears to be a flaky infrastructure issue. Do you have any recommendations as to how this should be handled?

[MikeGoldsmith]

Ah, I see the problem - sdk-extension-aws-1 is failing because of the move to __init__.py 😦

Adding opentelemetry-sdk/src/opentelemetry/sdk/__init__.py converts opentelemetry.sdk from an implicit namespace package into a regular package. This breaks namespace package resolution — Python stops scanning other sys.path entries for opentelemetry.sdk.* subpackages, so the separately-installed opentelemetry-sdk-extension-aws (which provides opentelemetry.sdk.extension.aws) becomes unfindable:

ModuleNotFoundError: No module named 'opentelemetry.sdk.extension'

We need to move it somewhere else, but then we'll lose the automatic resolution we wanted by putting it in init. Maybe put it back in _internal/init and add it to configure_otel_defaults() in opentelemetry.sdk._configuration?

[MikeGoldsmith]

Moving to request changes until we fix the resolution problem.

[emdneto]

Thanks for the PR!

Just a heads-up: we no longer update CHANGELOG.md directly. The changelog is now generated from changelog fragments using Towncrier.

Please add the appropriate changelog fragment for this change instead of editing CHANGELOG.md manually. You can find the instructions and expected format in CONTRIBUTING.md.

[grvmishra788]

Thanks for the PR!

Just a heads-up: we no longer update CHANGELOG.md directly. The changelog is now generated from changelog fragments using Towncrier.

Please add the appropriate changelog fragment for this change instead of editing CHANGELOG.md manually. You can find the instructions and expected format in CONTRIBUTING.md.

Thanks for letting me know. switched to Towncrier changelog fragment instead.

[tammy-baylis-swi]

This PR and the auto-instrumentation PR (open-telemetry/opentelemetry-python-contrib#4542) should not conflict but noting that OTEL_LOG_LEVEL will be applied to two different code paths: SDK internal logs, and auto-instrumentation startup logs

[pmcollins]

Maybe this should also map trace to debug. The OTEL_LOG_LEVEL spec doesn't define accepted values, but the declarative config schema includes trace. Since Python doesn't have trace, mapping trace to debug would align with the config model and with the debug startup messages PR that Tammy mentioned.

[grvmishra788]

Good call - done. "trace" now maps to DEBUG. Updated the dict, the warning message listing valid values, and the tests.

[grvmishra788]

Hi @MikeGoldsmith @emdneto @pmcollins - this PR has been open for a while and I believe all the feedback has been addressed. Would appreciate a final review & merge when you get a chance. Thanks!