opentelemetry-api: stabilize logs signal

.changelog/5731.changed

@@ -0,0 +1 @@
+`opentelemetry-api`: stabilize the logs API as `opentelemetry.logs`

.changelog/5731.deprecated

@@ -0,0 +1 @@
+`opentelemetry-api`: deprecate `opentelemetry._logs` in favor of `opentelemetry.logs`

docs/api/index.rst

@@ -14,10 +14,10 @@ For the concrete implementation of these interfaces, see the
 .. toctree::
     :maxdepth: 1
 
-    _logs
     attributes
     baggage
     context
+    logs
     propagate
     propagators
     trace

docs/api/logs.rst

@@ -0,0 +1,14 @@
+opentelemetry.logs package
+==========================
+
+Submodules
+----------
+
+.. toctree::
+
+   logs.severity
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.logs

docs/api/logs.severity.rst

@@ -0,0 +1,4 @@
+opentelemetry.logs.severity
+===========================
+
+.. automodule:: opentelemetry.logs.severity

docs/examples/logs/example.py

@@ -4,13 +4,13 @@
 import logging
 
 from opentelemetry import trace
-from opentelemetry._logs import set_logger_provider
 from opentelemetry.exporter.otlp.proto.grpc._log_exporter import (
     OTLPLogExporter,
 )
 
 # this is available in the opentelemetry-instrumentation-logging package
 from opentelemetry.instrumentation.logging.handler import LoggingHandler
+from opentelemetry.logs import set_logger_provider
 from opentelemetry.sdk._logs import LoggerProvider
 from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
 from opentelemetry.sdk.resources import Resource

docs/examples/metrics/sdk-metrics/sdk_metrics.py

@@ -4,7 +4,7 @@
 import os
 import time
 
-from opentelemetry import _logs, metrics, trace
+from opentelemetry import logs, metrics, trace
 from opentelemetry.exporter.otlp.proto.http._log_exporter import (
     OTLPLogExporter,
 )
@@ -60,10 +60,10 @@
         meter_provider=meter_provider,
     )
 )
-_logs.set_logger_provider(logger_provider)
+logs.set_logger_provider(logger_provider)
 
 tracer = trace.get_tracer(__name__)
-logger = _logs.get_logger(__name__)
+logger = logs.get_logger(__name__)
 
 with tracer.start_as_current_span("example-span"):
     logger.emit(body="example log record")

docs/examples/multi-destination-exporting/README.rst

@@ -62,6 +62,6 @@ Useful links
 - OpenTelemetry_
 - :doc:`../../api/trace`
 - :doc:`../../api/metrics`
-- :doc:`../../api/_logs`
+- :doc:`../../api/logs`
 
 .. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/

docs/examples/multi-destination-exporting/multi_destination_logs.py

@@ -9,7 +9,6 @@
 
 import logging
 
-from opentelemetry._logs import set_logger_provider
 from opentelemetry.exporter.otlp.proto.grpc._log_exporter import (
     OTLPLogExporter as GrpcLogExporter,
 )
@@ -19,6 +18,7 @@
 
 # this is available in the opentelemetry-instrumentation-logging package
 from opentelemetry.instrumentation.logging.handler import LoggingHandler
+from opentelemetry.logs import set_logger_provider
 from opentelemetry.sdk._logs import LoggerProvider
 from opentelemetry.sdk._logs.export import (
     BatchLogRecordProcessor,

exporter/opentelemetry-exporter-otlp-json-common/benchmarks/test_benchmark_log_encoder.py

@@ -3,8 +3,8 @@
 
 import pytest
 
-from opentelemetry._logs import SeverityNumber
 from opentelemetry.exporter.otlp.json.common._log_encoder import encode_logs
+from opentelemetry.logs import SeverityNumber
 from tests import TIME, make_log, make_log_context
 
 

exporter/opentelemetry-exporter-otlp-json-common/tests/__init__.py

@@ -4,7 +4,7 @@
 import dataclasses
 import unittest
 
-from opentelemetry._logs import LogRecord, SeverityNumber
+from opentelemetry.logs import LogRecord, SeverityNumber
 from opentelemetry.sdk._logs import ReadableLogRecord
 from opentelemetry.sdk.metrics.export import (
     AggregationTemporality,

exporter/opentelemetry-exporter-otlp-json-common/tests/test_log_encoder.py

@@ -3,14 +3,14 @@
 
 import unittest
 
-from opentelemetry._logs import LogRecord, SeverityNumber
 from opentelemetry.exporter.otlp.proto.common._internal import (
     _encode_attributes,
     _encode_span_id,
     _encode_trace_id,
     _encode_value,
 )
 from opentelemetry.exporter.otlp.proto.common._log_encoder import encode_logs
+from opentelemetry.logs import LogRecord, SeverityNumber
 from opentelemetry.proto.collector.logs.v1.logs_service_pb2 import (
     ExportLogsServiceRequest,
 )

exporter/opentelemetry-exporter-otlp-json-common/tests/test_proto_json_compatibility.py

@@ -17,7 +17,6 @@
 
 from google.protobuf.json_format import MessageToDict, ParseDict
 
-from opentelemetry._logs import SeverityNumber
 from opentelemetry.exporter.otlp.json.common._log_encoder import (
     encode_logs as json_encode_logs,
 )
@@ -36,6 +35,7 @@
 from opentelemetry.exporter.otlp.proto.common.trace_encoder import (
     encode_spans as proto_encode_spans,
 )
+from opentelemetry.logs import SeverityNumber
 from opentelemetry.proto.collector.logs.v1.logs_service_pb2 import (
     ExportLogsServiceRequest as PB2ExportLogsServiceRequest,
 )

exporter/opentelemetry-exporter-otlp-json-file/tests/test_log_exporter.py

@@ -10,12 +10,12 @@
 import unittest
 from unittest.mock import Mock
 
-from opentelemetry._logs import LogRecord, SeverityNumber
 from opentelemetry.exporter.otlp.json.common._log_encoder import encode_logs
 from opentelemetry.exporter.otlp.json.file._internal import _format_line
 from opentelemetry.exporter.otlp.json.file._log_exporter import (
     FileLogExporter,
 )
+from opentelemetry.logs import LogRecord, SeverityNumber
 from opentelemetry.proto_json.logs.v1.logs import LogsData
 from opentelemetry.sdk._logs import (
     LoggerProvider,

exporter/opentelemetry-exporter-otlp-json-http/tests/test_log_exporter.py

@@ -17,7 +17,6 @@
 from mocket import Mocket, Mocketizer, mocketize
 from mocket.mocks.mockhttp import Entry, Response
 
-from opentelemetry._logs import LogRecord, SeverityNumber
 from opentelemetry.exporter.http.transport._urllib3 import (
     Urllib3HTTPTransport,
 )
@@ -27,6 +26,7 @@
 from opentelemetry.exporter.otlp.json.http._log_exporter import (
     OTLPLogExporter,
 )
+from opentelemetry.logs import LogRecord, SeverityNumber
 from opentelemetry.sdk._logs import LoggerProvider
 from opentelemetry.sdk._logs.export import (
     InMemoryLogRecordExporter,

exporter/opentelemetry-exporter-otlp-proto-common/tests/test_log_encoder.py

@@ -3,14 +3,14 @@
 
 import unittest
 
-from opentelemetry._logs import LogRecord, SeverityNumber
 from opentelemetry.exporter.otlp.proto.common._internal import (
     _encode_attributes,
     _encode_span_id,
     _encode_trace_id,
     _encode_value,
 )
 from opentelemetry.exporter.otlp.proto.common._log_encoder import encode_logs
+from opentelemetry.logs import LogRecord, SeverityNumber
 from opentelemetry.proto.collector.logs.v1.logs_service_pb2 import (
     ExportLogsServiceRequest,
 )

exporter/opentelemetry-exporter-otlp-proto-grpc/tests/logs/test_otlp_logs_exporter.py

@@ -11,11 +11,11 @@
 from google.protobuf.json_format import MessageToDict
 from grpc import ChannelCredentials, Compression
 
-from opentelemetry._logs import LogRecord, SeverityNumber
 from opentelemetry.exporter.otlp.proto.common._internal import _encode_value
 from opentelemetry.exporter.otlp.proto.grpc._log_exporter import (
     OTLPLogExporter,
 )
+from opentelemetry.logs import LogRecord, SeverityNumber
 from opentelemetry.proto.collector.logs.v1.logs_service_pb2 import (
     ExportLogsServiceRequest,
 )

exporter/opentelemetry-exporter-otlp-proto-http/tests/test_proto_log_exporter.py

@@ -16,7 +16,6 @@
 from mocket import Mocket, Mocketizer, mocketize
 from mocket.mocks.mockhttp import Entry, Response
 
-from opentelemetry._logs import LogRecord, SeverityNumber
 from opentelemetry.exporter.http.transport._requests import (
     RequestsHTTPTransport,
 )
@@ -36,6 +35,7 @@
     OTLPLogExporter,
 )
 from opentelemetry.exporter.otlp.proto.http.version import __version__
+from opentelemetry.logs import LogRecord, SeverityNumber
 from opentelemetry.proto.collector.logs.v1.logs_service_pb2 import (
     ExportLogsServiceRequest,
 )

opentelemetry-api/pyproject.toml

@@ -37,6 +37,9 @@ contextvars_context = "opentelemetry.context.contextvars_context:ContextVarsRunt
 [project.entry-points.opentelemetry_environment_variables]
 api = "opentelemetry.environment_variables"
 
+[project.entry-points.opentelemetry_logger_provider]
+default_logger_provider = "opentelemetry.logs:NoOpLoggerProvider"
+
 [project.entry-points.opentelemetry_meter_provider]
 default_meter_provider = "opentelemetry.metrics:NoOpMeterProvider"
 

opentelemetry-api/src/opentelemetry/_logs/__init__.py

@@ -1,38 +1,40 @@
 # Copyright The OpenTelemetry Authors
 # SPDX-License-Identifier: Apache-2.0
 """
-The OpenTelemetry logging API describes the classes used to generate logs and events.
+Deprecated alias of :mod:`opentelemetry.logs`.
 
-The :class:`.LoggerProvider` provides users access to the :class:`.Logger`.
-
-This module provides abstract (i.e. unimplemented) classes required for
-logging, and a concrete no-op implementation :class:`.NoOpLogger` that allows applications
-to use the API package alone without a supporting implementation.
-
-To get a logger, you need to provide the package name from which you are
-calling the logging APIs to OpenTelemetry by calling `LoggerProvider.get_logger`
-with the calling module name and the version of your package.
-
-The following code shows how to obtain a logger using the global :class:`.LoggerProvider`::
-
-    from opentelemetry._logs import get_logger
-
-    logger = get_logger("example-logger")
-
-.. versionadded:: 1.15.0
+.. deprecated:: 1.46.0
+    This module will be removed in a future release. Use
+    :mod:`opentelemetry.logs` instead.
 """
 
-from opentelemetry._logs._internal import (
+import sys
+import warnings
+
+from opentelemetry.logs import (
     Logger,
     LoggerProvider,
     LogRecord,
     NoOpLogger,
     NoOpLoggerProvider,
+    SeverityNumber,
+    _internal,
     get_logger,
     get_logger_provider,
     set_logger_provider,
+    severity,
 )
-from opentelemetry._logs.severity import SeverityNumber
+
+warnings.warn(
+    "The opentelemetry._logs module is deprecated since version 1.46.0 "
+    "and will be removed in a future release. "
+    "Use opentelemetry.logs instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+sys.modules[f"{__name__}._internal"] = _internal
+sys.modules[f"{__name__}.severity"] = severity
 
 __all__ = [
     "LogRecord",

opentelemetry-api/src/opentelemetry/environment_variables/__init__.py

@@ -66,7 +66,9 @@
 .. envvar:: OTEL_PYTHON_METER_PROVIDER
 """
 
-_OTEL_PYTHON_LOGGER_PROVIDER = "OTEL_PYTHON_LOGGER_PROVIDER"
+OTEL_PYTHON_LOGGER_PROVIDER = "OTEL_PYTHON_LOGGER_PROVIDER"
 """
 .. envvar:: OTEL_PYTHON_LOGGER_PROVIDER
 """
+
+_OTEL_PYTHON_LOGGER_PROVIDER = OTEL_PYTHON_LOGGER_PROVIDER

opentelemetry-api/src/opentelemetry/logs/__init__.py

@@ -0,0 +1,47 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+"""
+The OpenTelemetry logging API describes the classes used to generate logs and events.
+
+The :class:`.LoggerProvider` provides users access to the :class:`.Logger`.
+
+This module provides abstract (i.e. unimplemented) classes required for
+logging, and a concrete no-op implementation :class:`.NoOpLogger` that allows applications
+to use the API package alone without a supporting implementation.
+
+To get a logger, you need to provide the package name from which you are
+calling the logging APIs to OpenTelemetry by calling `LoggerProvider.get_logger`
+with the calling module name and the version of your package.
+
+The following code shows how to obtain a logger using the global :class:`.LoggerProvider`::
+
+    from opentelemetry.logs import get_logger
+
+    logger = get_logger("example-logger")
+
+.. versionadded:: 1.15.0
+"""
+
+from opentelemetry.logs._internal import (
+    Logger,
+    LoggerProvider,
+    LogRecord,
+    NoOpLogger,
+    NoOpLoggerProvider,
+    get_logger,
+    get_logger_provider,
+    set_logger_provider,
+)
+from opentelemetry.logs.severity import SeverityNumber
+
+__all__ = [
+    "LogRecord",
+    "Logger",
+    "LoggerProvider",
+    "NoOpLogger",
+    "NoOpLoggerProvider",
+    "SeverityNumber",
+    "get_logger",
+    "get_logger_provider",
+    "set_logger_provider",
+]