Update logging to include logging api as per specification (#3038)

Author: lzchen

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#3026](https://github.com/open-telemetry/opentelemetry-python/pull/3026))
 - Add missing entry points for OTLP/HTTP exporter
   ([#3027](https://github.com/open-telemetry/opentelemetry-python/pull/3027))
+- Update logging to include logging api as per specification
+  ([#3038](https://github.com/open-telemetry/opentelemetry-python/pull/3038))
 - Fix: Avoid generator in metrics _ViewInstrumentMatch.collect()
   ([#3035](https://github.com/open-telemetry/opentelemetry-python/pull/3035)
 

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/api/index.rst

@@ -6,6 +6,7 @@ OpenTelemetry Python API
 .. toctree::
     :maxdepth: 1
 
+    _logs
     baggage
     context
     propagate

docs/sdk/_logs.rst

@@ -0,0 +1,7 @@
+opentelemetry.sdk._logs package
+===============================
+
+.. automodule:: opentelemetry.sdk._logs
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/sdk/index.rst

@@ -6,9 +6,9 @@ OpenTelemetry Python SDK
 .. toctree::
     :maxdepth: 1
 
+    _logs
     resources
     trace
     metrics
-    logs
     error_handler
     environment_variables

docs/sdk/logs.export.rst

@@ -21,6 +21,7 @@
 from google.rpc.error_details_pb2 import RetryInfo
 from grpc import StatusCode, server
 
+from opentelemetry._logs import SeverityNumber
 from opentelemetry.exporter.otlp.proto.grpc._log_exporter import (
     OTLPLogExporter,
 )
@@ -45,9 +46,6 @@
 )
 from opentelemetry.sdk._logs import LogData, LogRecord
 from opentelemetry.sdk._logs.export import LogExportResult
-from opentelemetry.sdk._logs.severity import (
-    SeverityNumber as SDKSeverityNumber,
-)
 from opentelemetry.sdk.resources import Resource as SDKResource
 from opentelemetry.sdk.util.instrumentation import InstrumentationScope
 from opentelemetry.trace import TraceFlags
@@ -117,7 +115,7 @@ def setUp(self):
                 span_id=5213367945872657620,
                 trace_flags=TraceFlags(0x01),
                 severity_text="WARNING",
-                severity_number=SDKSeverityNumber.WARN,
+                severity_number=SeverityNumber.WARN,
                 body="Zhengzhou, We have a heaviest rains in 1000 years",
                 resource=SDKResource({"key": "value"}),
                 attributes={"a": 1, "b": "c"},
@@ -133,7 +131,7 @@ def setUp(self):
                 span_id=5213367945872657623,
                 trace_flags=TraceFlags(0x01),
                 severity_text="INFO",
-                severity_number=SDKSeverityNumber.INFO2,
+                severity_number=SeverityNumber.INFO2,
                 body="Sydney, Opera House is closed",
                 resource=SDKResource({"key": "value"}),
                 attributes={"custom_attr": [1, 2, 3]},
@@ -149,7 +147,7 @@ def setUp(self):
                 span_id=5213367945872657628,
                 trace_flags=TraceFlags(0x01),
                 severity_text="ERROR",
-                severity_number=SDKSeverityNumber.WARN,
+                severity_number=SeverityNumber.WARN,
                 body="Mumbai, Boil water before drinking",
                 resource=SDKResource({"service": "myapp"}),
             ),

docs/sdk/logs.rst

@@ -21,6 +21,7 @@
 import requests
 import responses
 
+from opentelemetry._logs import SeverityNumber
 from opentelemetry.exporter.otlp.proto.http import Compression
 from opentelemetry.exporter.otlp.proto.http._log_exporter import (
     DEFAULT_COMPRESSION,
@@ -54,7 +55,6 @@
 )
 from opentelemetry.sdk._logs import LogData
 from opentelemetry.sdk._logs import LogRecord as SDKLogRecord
-from opentelemetry.sdk._logs.severity import SeverityNumber
 from opentelemetry.sdk.environment_variables import (
     OTEL_EXPORTER_OTLP_CERTIFICATE,
     OTEL_EXPORTER_OTLP_COMPRESSION,

docs/sdk/logs.severity.rst

@@ -0,0 +1,58 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+The OpenTelemetry logging API describes the classes used to generate logs and events.
+
+The :class:`.LoggerProvider` provides users access to the :class:`.Logger` which in
+turn is used to create :class:`.Event` and :class:`.Log` objects.
+
+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
+"""
+
+# pylint: disable=unused-import
+
+from opentelemetry._logs._internal import (  # noqa: F401
+    Logger,
+    LoggerProvider,
+    LogRecord,
+    NoOpLogger,
+    NoOpLoggerProvider,
+    get_logger,
+    get_logger_provider,
+    set_logger_provider,
+)
+from opentelemetry._logs.severity import (  # noqa: F401
+    SeverityNumber,
+    std_to_otel,
+)
+
+__all__ = []
+for key, value in globals().copy().items():  # type: ignore
+    if not key.startswith("_"):
+        value.__module__ = __name__  # type: ignore
+        __all__.append(key)