exporters: stabilize logs signal

.changelog/5733.added

@@ -0,0 +1 @@
+`opentelemetry-exporter-otlp-json-http`, `opentelemetry-exporter-otlp-json-file`: export the log exporter at the package top level

.changelog/5733.changed

@@ -0,0 +1 @@
+`opentelemetry-exporter-otlp-proto-grpc`, `opentelemetry-exporter-otlp-proto-http`, `opentelemetry-exporter-otlp-json-http`, `opentelemetry-exporter-otlp-json-file`: stabilize the log exporter as the public `log_exporter` module

.changelog/5733.changed.1

@@ -0,0 +1 @@
+`opentelemetry-exporter-otlp-proto-common`, `opentelemetry-exporter-otlp-json-common`: stabilize the log encoder as the public `log_encoder` module

.changelog/5733.deprecated

@@ -0,0 +1 @@
+`opentelemetry-exporter-otlp-proto-grpc`, `opentelemetry-exporter-otlp-proto-http`, `opentelemetry-exporter-otlp-json-http`, `opentelemetry-exporter-otlp-json-file`: deprecate the `_log_exporter` module in favor of `log_exporter`

.changelog/5733.deprecated.1

@@ -0,0 +1 @@
+ `opentelemetry-exporter-otlp-proto-common`, `opentelemetry-exporter-otlp-json-common`: deprecate the `_log_encoder` module in favor of `log_encoder`

README.md

@@ -14,15 +14,10 @@ See the [OpenTelemetry Instrumentation for Python](https://opentelemetry.io/docs
 | ------- | ------------ | ------- |
 | Traces  | Stable       | N/A     |
 | Metrics | Stable       | N/A     |
-| Logs    | Development* | N/A     |
+| Logs    | Stable       | N/A     |
 
 Project versioning information and stability guarantees can be found [here](./rationale.md#versioning-and-releasing).
 
-***Breaking Changes**
-
-> [!IMPORTANT]
-> We are working on stabilizing the Log signal which would require making deprecations and breaking changes. We will try to reduce the releases that may require an update to your code, especially for instrumentations or for SDK developers.
-
 ## Getting started
 
 You can find the getting started guide for OpenTelemetry Python [here](https://opentelemetry.io/docs/languages/python/getting-started/).

docs/examples/logs/README.rst

@@ -3,13 +3,6 @@ OpenTelemetry Logs SDK
 
 The source files of these examples are available :scm_web:`here <docs/examples/logs/>`.
 
-.. note::
-
-   ``LoggingHandler`` has moved from the SDK to the
-   ``opentelemetry-instrumentation-logging`` package in the contrib repo
-   and is deprecated in ``opentelemetry-sdk``.
-
-
 Installation
 ------------
 

docs/examples/logs/example.py

@@ -4,7 +4,7 @@
 import logging
 
 from opentelemetry import trace
-from opentelemetry.exporter.otlp.proto.grpc._log_exporter import (
+from opentelemetry.exporter.otlp.proto.grpc.log_exporter import (
     OTLPLogExporter,
 )
 

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

@@ -5,7 +5,7 @@
 import time
 
 from opentelemetry import logs, metrics, trace
-from opentelemetry.exporter.otlp.proto.http._log_exporter import (
+from opentelemetry.exporter.otlp.proto.http.log_exporter import (
     OTLPLogExporter,
 )
 from opentelemetry.exporter.otlp.proto.http.metric_exporter import (

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

@@ -9,10 +9,10 @@
 
 import logging
 
-from opentelemetry.exporter.otlp.proto.grpc._log_exporter import (
+from opentelemetry.exporter.otlp.proto.grpc.log_exporter import (
     OTLPLogExporter as GrpcLogExporter,
 )
-from opentelemetry.exporter.otlp.proto.http._log_exporter import (
+from opentelemetry.exporter.otlp.proto.http.log_exporter import (
     OTLPLogExporter as HttpLogExporter,
 )
 

docs/exporter/otlp/otlp.rst

@@ -23,7 +23,7 @@ opentelemetry.exporter.otlp.proto.http
     :undoc-members:
     :show-inheritance:
 
-.. automodule:: opentelemetry.exporter.otlp.proto.http._log_exporter
+.. automodule:: opentelemetry.exporter.otlp.proto.http.log_exporter
     :members:
     :undoc-members:
     :show-inheritance:
@@ -46,7 +46,7 @@ opentelemetry.exporter.otlp.proto.grpc
     :undoc-members:
     :show-inheritance:
 
-.. automodule:: opentelemetry.exporter.otlp.proto.grpc._log_exporter
+.. automodule:: opentelemetry.exporter.otlp.proto.grpc.log_exporter
     :members:
     :undoc-members:
     :show-inheritance:
@@ -68,7 +68,7 @@ opentelemetry.exporter.otlp.json.file
     :undoc-members:
     :show-inheritance:
 
-.. automodule:: opentelemetry.exporter.otlp.json.file._log_exporter
+.. automodule:: opentelemetry.exporter.otlp.json.file.log_exporter
     :members:
     :undoc-members:
     :show-inheritance:
@@ -90,7 +90,7 @@ opentelemetry.exporter.otlp.json.http
     :undoc-members:
     :show-inheritance:
 
-.. automodule:: opentelemetry.exporter.otlp.json.http._log_exporter
+.. automodule:: opentelemetry.exporter.otlp.json.http.log_exporter
     :members:
     :undoc-members:
     :show-inheritance:

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

@@ -3,7 +3,7 @@
 
 import pytest
 
-from opentelemetry.exporter.otlp.json.common._log_encoder import encode_logs
+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/src/opentelemetry/exporter/otlp/json/common/_log_encoder.py

@@ -1,8 +1,27 @@
 # Copyright The OpenTelemetry Authors
 # SPDX-License-Identifier: Apache-2.0
+"""
+Deprecated alias of :mod:`opentelemetry.exporter.otlp.json.common.log_encoder`.
 
-from opentelemetry.exporter.otlp.json.common._internal._log_encoder import (
+.. deprecated:: 1.46.0
+    This module will be removed in a future release. Use
+    :mod:`opentelemetry.exporter.otlp.json.common.log_encoder` instead.
+"""
+
+import warnings
+
+from opentelemetry.exporter.otlp.json.common.log_encoder import (
     encode_logs,
 )
 
-__all__ = ["encode_logs"]
+warnings.warn(
+    "The opentelemetry.exporter.otlp.json.common._log_encoder module is deprecated since version 1.46.0 "
+    "and will be removed in a future release. "
+    "Use opentelemetry.exporter.otlp.json.common.log_encoder instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+__all__ = [
+    "encode_logs",
+]

exporter/opentelemetry-exporter-otlp-json-common/src/opentelemetry/exporter/otlp/json/common/log_encoder.py

@@ -0,0 +1,8 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+from opentelemetry.exporter.otlp.json.common._internal.log_encoder import (
+    encode_logs,
+)
+
+__all__ = ["encode_logs"]

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

@@ -0,0 +1,58 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import importlib
+import sys
+import unittest
+from importlib.metadata import EntryPoint
+
+import opentelemetry.exporter.otlp.json.common.log_encoder
+
+_DEPRECATED_MODULE = "opentelemetry.exporter.otlp.json.common._log_encoder"
+
+
+def _unload_deprecated_module() -> None:
+    sys.modules.pop(_DEPRECATED_MODULE, None)
+    sys.modules["opentelemetry.exporter.otlp.json.common"].__dict__.pop("_log_encoder", None)
+
+
+class TestDeprecatedLogModule(unittest.TestCase):
+    def setUp(self) -> None:
+        _unload_deprecated_module()
+
+    def test_import_emits_deprecation_warning(self) -> None:
+        with self.assertWarns(DeprecationWarning) as context:
+            importlib.import_module(_DEPRECATED_MODULE)
+        message = str(context.warning)
+        self.assertIn("opentelemetry.exporter.otlp.json.common.log_encoder", message)
+        self.assertIn("will be removed in a future release", message)
+
+    def test_deprecation_warning_points_at_importer(self) -> None:
+        # pylint: disable=import-outside-toplevel,unused-import
+        # A literal import statement is required here since importlib.import_module
+        # would attribute the warning to importlib itself.
+        with self.assertWarns(DeprecationWarning) as context:
+            from opentelemetry.exporter.otlp.json.common._log_encoder import encode_logs  # noqa: F401, PLC0415
+        self.assertEqual(context.filename, __file__)
+
+    def test_reexports_are_identical(self) -> None:
+        with self.assertWarns(DeprecationWarning):
+            deprecated = importlib.import_module(_DEPRECATED_MODULE)
+
+        self.assertEqual(deprecated.__all__, ["encode_logs"])
+        for name in deprecated.__all__:
+            with self.subTest(name=name):
+                self.assertIs(
+                    getattr(deprecated, name), getattr(opentelemetry.exporter.otlp.json.common.log_encoder, name)
+                )
+
+    def test_old_entry_point_target_resolves(self) -> None:
+        # Entry points and configuration may still reference the old module path.
+        entry_point = EntryPoint(
+            name="log_encoder", value="opentelemetry.exporter.otlp.json.common._log_encoder:encode_logs", group="test"
+        )
+        with self.assertWarns(DeprecationWarning):
+            target = entry_point.load()
+        self.assertIs(target, opentelemetry.exporter.otlp.json.common.log_encoder.encode_logs)

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

@@ -9,7 +9,7 @@
     _encode_trace_id,
     _encode_value,
 )
-from opentelemetry.exporter.otlp.proto.common._log_encoder import encode_logs
+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,7 @@
 
 from google.protobuf.json_format import MessageToDict, ParseDict
 
-from opentelemetry.exporter.otlp.json.common._log_encoder import (
+from opentelemetry.exporter.otlp.json.common.log_encoder import (
     encode_logs as json_encode_logs,
 )
 from opentelemetry.exporter.otlp.json.common.metrics_encoder import (
@@ -26,7 +26,7 @@
 from opentelemetry.exporter.otlp.json.common.trace_encoder import (
     encode_spans as json_encode_spans,
 )
-from opentelemetry.exporter.otlp.proto.common._log_encoder import (
+from opentelemetry.exporter.otlp.proto.common.log_encoder import (
     encode_logs as proto_encode_logs,
 )
 from opentelemetry.exporter.otlp.proto.common.metrics_encoder import (

exporter/opentelemetry-exporter-otlp-json-file/pyproject.toml

@@ -38,7 +38,7 @@ otlp_json_file = "opentelemetry.exporter.otlp.json.file.trace_exporter:FileSpanE
 otlp_json_file = "opentelemetry.exporter.otlp.json.file.metric_exporter:FileMetricExporter"
 
 [project.entry-points.opentelemetry_logs_exporter]
-otlp_json_file = "opentelemetry.exporter.otlp.json.file._log_exporter:FileLogExporter"
+otlp_json_file = "opentelemetry.exporter.otlp.json.file.log_exporter:FileLogExporter"
 
 [project.urls]
 Homepage = "https://github.com/open-telemetry/opentelemetry-python/tree/main/exporter/opentelemetry-exporter-otlp-json-file"

exporter/opentelemetry-exporter-otlp-json-file/src/opentelemetry/exporter/otlp/json/file/__init__.py

@@ -16,7 +16,7 @@
 
 - :class:`~opentelemetry.exporter.otlp.json.file.trace_exporter.FileSpanExporter` - traces
 - :class:`~opentelemetry.exporter.otlp.json.file.metric_exporter.FileMetricExporter` - metrics
-- :class:`~opentelemetry.exporter.otlp.json.file._log_exporter.FileLogExporter` - logs
+- :class:`~opentelemetry.exporter.otlp.json.file.log_exporter.FileLogExporter` - logs
 
 Each exporter accepts a destination in one of three ways:
 
@@ -60,6 +60,9 @@
 ---
 """
 
+from opentelemetry.exporter.otlp.json.file.log_exporter import (
+    FileLogExporter,
+)
 from opentelemetry.exporter.otlp.json.file.metric_exporter import (
     FileMetricExporter,
 )
@@ -68,6 +71,7 @@
 )
 
 __all__ = [
+    "FileLogExporter",
     "FileMetricExporter",
     "FileSpanExporter",
 ]

exporter/opentelemetry-exporter-otlp-json-file/src/opentelemetry/exporter/otlp/json/file/_log_exporter.py

@@ -1,70 +1,27 @@
 # Copyright The OpenTelemetry Authors
 # SPDX-License-Identifier: Apache-2.0
+"""
+Deprecated alias of :mod:`opentelemetry.exporter.otlp.json.file.log_exporter`.
 
-import logging
-import os
-from collections.abc import Sequence
-from typing import IO, Any, overload
+.. deprecated:: 1.46.0
+    This module will be removed in a future release. Use
+    :mod:`opentelemetry.exporter.otlp.json.file.log_exporter` instead.
+"""
 
-from opentelemetry.exporter.otlp.json.common._log_encoder import encode_logs
-from opentelemetry.exporter.otlp.json.file._internal import _FileExporter
-from opentelemetry.sdk._shared_internal import DuplicateFilter
-from opentelemetry.sdk.logs import ReadableLogRecord
-from opentelemetry.sdk.logs.export import (
-    LogRecordExporter,
-    LogRecordExportResult,
-)
-
-_logger = logging.getLogger(__name__)
-_logger.addFilter(DuplicateFilter())
-
-
-def _encode_logs_to_dict(
-    batch: Sequence[ReadableLogRecord],
-) -> dict[str, Any] | None:
-    data = encode_logs(batch)
-    return data.to_dict() if data.resource_logs else None
-
-
-class FileLogExporter(LogRecordExporter):
-    @overload
-    def __init__(
-        self,
-        path: str | os.PathLike[str],
-    ) -> None: ...
+import warnings
 
-    @overload
-    def __init__(
-        self,
-        *,
-        stream: IO[str],
-    ) -> None: ...
-
-    @overload
-    def __init__(
-        self,
-    ) -> None: ...
-
-    def __init__(
-        self,
-        path: str | os.PathLike[str] | None = None,
-        *,
-        stream: IO[str] | None = None,
-    ) -> None:
-        self._exporter: _FileExporter[Sequence[ReadableLogRecord]] = _FileExporter(
-            encode=_encode_logs_to_dict,
-            kind="logs",
-            logger=_logger,
-            path=path,
-            stream=stream,
-        )
-
-    def export(self, batch: Sequence[ReadableLogRecord]) -> LogRecordExportResult:
-        return LogRecordExportResult.SUCCESS if self._exporter.export(batch) else LogRecordExportResult.FAILURE
+from opentelemetry.exporter.otlp.json.file.log_exporter import (
+    FileLogExporter,
+)
 
-    def shutdown(self) -> None:
-        self._exporter.shutdown()
+warnings.warn(
+    "The opentelemetry.exporter.otlp.json.file._log_exporter module is deprecated since version 1.46.0 "
+    "and will be removed in a future release. "
+    "Use opentelemetry.exporter.otlp.json.file.log_exporter instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
 
-    # pylint: disable-next=no-self-use
-    def force_flush(self, timeout_millis: int = 10_000) -> bool:
-        return True
+__all__ = [
+    "FileLogExporter",
+]