opentelemetry-api: stabilize logs signal

[herin049]

Description

Part 1/3 of the logs stabilization stack (API -> SDK -> exporters).

Stabilizes the logs signal in the API package by moving it from opentelemetry._logs to the public opentelemetry.logs package.

• Moves opentelemetry._logs (including severity) to opentelemetry.logs, with a py.typed marker.
• Keeps opentelemetry._logs as a deprecated alias, re-exporting everything from opentelemetry.logs while emitting a DeprecationWarning and maps opentelemetry._logs._internal / .severity to the new modules
• Makes OTEL_PYTHON_LOGGER_PROVIDER public (the private _OTEL_PYTHON_LOGGER_PROVIDER alias is kept) and registers NoOpLoggerProvider as the default opentelemetry_logger_provider entry point, matching traces and metrics.
• Updates all repo imports and the API docs (docs/api/logs*.rst).

Fixes #3361

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

uv run tox -e py314-test-opentelemetry-api

Does This PR Require a Contrib Repo Change?

• Yes. - Link to PR:
• No.

Checklist:

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

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on reviewers · refreshed 2026-10-03 04:00 UTC

Review the latest changes.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

[Copilot]

Copilot review overview

🟡 Changes recommended

Deprecated submodule paths need static import compatibility for existing type-checked consumers.

Review effort: Balanced
Findings: 1

Open (1)

• Add compatibility stubs for deprecated log submodule imports · New

What changed in this PR

Stabilizes the logs API as opentelemetry.logs, the first step toward stabilizing logs across the API, SDK, and exporters.

Changes:

• Adds the public logs package and deprecated runtime aliases.
• Exposes logger-provider configuration and registers the default no-op provider.
• Migrates repository imports, documentation, and tests.

File	Description
tests/​opentelemetry-test-utils/​tests/​test_otlp_test_server.py	Uses public logs import.
tests/​opentelemetry-test-utils/​src/​opentelemetry/​test/​globals_test.py	Resets public logs state.
tests/​opentelemetry-docker-tests/​tests/​otlpexporter/​test_otlp_logs_functional.py	Migrates functional-test imports.
opentelemetry-sdk/​tests/​shared_internal/​test_batch_processor.py	Uses public LogRecord.
opentelemetry-sdk/​tests/​logs/​test_multi_log_processor.py	Migrates processor-test imports.
opentelemetry-sdk/​tests/​logs/​test_logs.py	Migrates logs-test imports.
opentelemetry-sdk/​tests/​logs/​test_log_record.py	Migrates record-test imports.
opentelemetry-sdk/​tests/​logs/​test_handler.py	Migrates handler-test imports.
opentelemetry-sdk/​tests/​logs/​test_export.py	Migrates export-test imports.
opentelemetry-sdk/​tests/​logs/​scripts/​logger_provider_resource_after_fork.py	Uses public LogRecord.
opentelemetry-sdk/​src/​opentelemetry/​sdk/​_logs/​_internal/​_exceptions.py	Uses public LogRecord.
opentelemetry-sdk/​src/​opentelemetry/​sdk/​_logs/​_internal/​__init__.py	Integrates public logs API.
opentelemetry-sdk/​src/​opentelemetry/​sdk/​_configuration/​__init__.py	Uses public provider setter.
opentelemetry-sdk/​benchmarks/​logs/​test_benchmark_logs.py	Migrates benchmark import.
opentelemetry-configuration/​tests/​test_logger_provider.py	Uses public provider getter.
opentelemetry-configuration/​src/​opentelemetry/​configuration/​_logger_provider.py	Uses public provider setter.
opentelemetry-api/​tests/​logs/​test_proxy.py	Targets public logs proxies.
opentelemetry-api/​tests/​logs/​test_logger_provider.py	Updates imports and patch targets.
opentelemetry-api/​tests/​logs/​test_log_record.py	Updates import and patch target.
opentelemetry-api/​tests/​logs/​test_deprecated_logs_module.py	Tests warnings and runtime compatibility.
opentelemetry-api/​src/​opentelemetry/​logs/​severity/​__init__.py	Exposes public severity enum.
opentelemetry-api/​src/​opentelemetry/​logs/​py.typed	Marks public package as typed.
opentelemetry-api/​src/​opentelemetry/​logs/​_internal/​__init__.py	Relocates logs implementation.
opentelemetry-api/​src/​opentelemetry/​logs/​__init__.py	Exports public logs API.
opentelemetry-api/​src/​opentelemetry/​environment_variables/​__init__.py	Publishes logger-provider constant.
opentelemetry-api/​src/​opentelemetry/​_logs/​__init__.py	Provides deprecated runtime aliases.
opentelemetry-api/​pyproject.toml	Registers no-op logger provider.
exporter/​opentelemetry-exporter-otlp-proto-http/​tests/​test_proto_log_exporter.py	Migrates exporter-test imports.
exporter/​opentelemetry-exporter-otlp-proto-grpc/​tests/​logs/​test_otlp_logs_exporter.py	Migrates exporter-test imports.
exporter/​opentelemetry-exporter-otlp-proto-common/​tests/​test_log_encoder.py	Migrates encoder-test imports.
exporter/​opentelemetry-exporter-otlp-json-http/​tests/​test_log_exporter.py	Migrates exporter-test imports.
exporter/​opentelemetry-exporter-otlp-json-file/​tests/​test_log_exporter.py	Migrates exporter-test imports.
exporter/​opentelemetry-exporter-otlp-json-common/​tests/​test_proto_json_compatibility.py	Migrates compatibility-test import.
exporter/​opentelemetry-exporter-otlp-json-common/​tests/​test_log_encoder.py	Migrates encoder-test imports.
exporter/​opentelemetry-exporter-otlp-json-common/​tests/​__init__.py	Migrates test-helper imports.
exporter/​opentelemetry-exporter-otlp-json-common/​benchmarks/​test_benchmark_log_encoder.py	Migrates benchmark import.
docs/​examples/​multi-destination-exporting/​README.rst	Links public API documentation.
docs/​examples/​multi-destination-exporting/​multi_destination_logs.py	Uses public provider setter.
docs/​examples/​metrics/​sdk-metrics/​sdk_metrics.py	Uses public logs namespace.
docs/​examples/​logs/​example.py	Uses public provider setter.
docs/​api/​logs.severity.rst	Documents public severity module.
docs/​api/​logs.rst	Documents public logs package.
docs/​api/​index.rst	Links public logs documentation.
docs/​api/​_logs.severity.rst	Removes old severity page.
docs/​api/​_logs.rst	Removes old logs page.
.changelog/​5731.deprecated	Announces deprecated namespace.
.changelog/​5731.changed	Announces API stabilization.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.