Update SDK docs and Add example with OTEL collector logging (debug) exporter

.gitignore

@@ -25,6 +25,7 @@ __pycache__
 venv*/
 .venv*/
 opentelemetry-python-contrib/
+include
 # in case of symlink
 opentelemetry-python-contrib
 

docs/examples/logs/README.rst

@@ -0,0 +1,75 @@
+OpenTelemetry Logs SDK
+======================
+
+Start the Collector locally to see data being exported. Write the following file:
+
+.. code-block:: yaml
+
+    # otel-collector-config.yaml
+    receivers:
+        otlp:
+            protocols:
+                grpc:
+
+    exporters:
+        logging:
+
+    processors:
+        batch:
+
+Then start the Docker container:
+
+.. code-block:: sh
+
+    docker run \
+        -p 4317:4317 \
+        -v $(pwd)/otel-collector-config.yaml:/etc/otel/config.yaml \
+        otel/opentelemetry-collector-contrib:latest
+
+.. code-block:: sh
+
+    $ python example.py
+
+The resulting logs will appear in the output from the collector and look similar to this:
+
+.. code-block:: sh
+
+        ResourceLog #0
+        Resource labels:
+             -> telemetry.sdk.language: STRING(python)
+             -> telemetry.sdk.name: STRING(opentelemetry)
+             -> telemetry.sdk.version: STRING(1.5.0.dev0)
+             -> service.name: STRING(unknown_service)
+        InstrumentationLibraryLogs #0
+        InstrumentationLibrary __main__ 0.1
+        LogRecord #0
+        Timestamp: 2021-08-18 08:26:53.837349888 +0000 UTC
+        Severity: ERROR
+        ShortName:
+        Body: Exception while exporting logs.
+        ResourceLog #1
+        Resource labels:
+             -> telemetry.sdk.language: STRING(python)
+             -> telemetry.sdk.name: STRING(opentelemetry)
+             -> telemetry.sdk.version: STRING(1.5.0.dev0)
+             -> service.name: STRING(unknown_service)
+        InstrumentationLibraryLogs #0
+        InstrumentationLibrary __main__ 0.1
+        LogRecord #0
+        Timestamp: 2021-08-18 08:26:53.842546944 +0000 UTC
+        Severity: ERROR
+        ShortName:
+        Body: The five boxing wizards jump quickly.
+        ResourceLog #2
+        Resource labels:
+             -> telemetry.sdk.language: STRING(python)
+             -> telemetry.sdk.name: STRING(opentelemetry)
+             -> telemetry.sdk.version: STRING(1.5.0.dev0)
+             -> service.name: STRING(unknown_service)
+        InstrumentationLibraryLogs #0
+        InstrumentationLibrary __main__ 0.1
+        LogRecord #0
+        Timestamp: 2021-08-18 08:26:53.843979008 +0000 UTC
+        Severity: ERROR
+        ShortName:
+        Body: Hyderabad, we have a major problem.

docs/examples/logs/example.py

@@ -0,0 +1,46 @@
+import logging
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.grpc.log_exporter import OTLPLogExporter
+from opentelemetry.sdk.logs import OTLPHandler, get_log_emitter_provider
+from opentelemetry.sdk.logs.export import SimpleLogProcessor
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import (
+    ConsoleSpanExporter,
+    SimpleSpanProcessor,
+)
+
+trace.set_tracer_provider(TracerProvider())
+trace.get_tracer_provider().add_span_processor(
+    SimpleSpanProcessor(ConsoleSpanExporter())
+)
+
+log_emitter_provider = get_log_emitter_provider()
+exporter = OTLPLogExporter(insecure=True)
+log_emitter_provider.add_log_processor(SimpleLogProcessor(exporter))
+log_emitter = log_emitter_provider.get_log_emitter(__name__, "0.1")
+handler = OTLPHandler(level=logging.NOTSET, log_emitter=log_emitter)
+
+# Attach OTLP handler to root logger
+logging.getLogger("root").addHandler(handler)
+
+# Log directly
+logging.info("Jackdaws love my big sphinx of quartz.")
+
+# Create different namespaced loggers
+logger1 = logging.getLogger("myapp.area1")
+logger2 = logging.getLogger("myapp.area2")
+
+logger1.debug("Quick zephyrs blow, vexing daft Jim.")
+logger1.info("How quickly daft jumping zebras vex.")
+logger2.warning("Jail zesty vixen who grabbed pay from quack.")
+logger2.error("The five boxing wizards jump quickly.")
+
+
+# Trace context correlation
+tracer = trace.get_tracer(__name__)
+with tracer.start_as_current_span("foo"):
+    # Do something
+    logger2.error("Hyderabad, we have a major problem.")
+
+log_emitter_provider.shutdown()

docs/examples/logs/otel-collector-config.yaml

@@ -0,0 +1,10 @@
+receivers:
+  otlp:
+    protocols:
+      grpc:
+
+exporters:
+  logging:
+
+processors:
+  batch:

docs/sdk/logs.export.rst

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

docs/sdk/logs.rst

@@ -0,0 +1,15 @@
+opentelemetry.sdk.logs package
+===============================
+
+Submodules
+----------
+
+.. toctree::
+
+   logs.export
+   logs.severity
+
+.. automodule:: opentelemetry.sdk.logs
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/sdk/logs.severity.rst

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

docs/sdk/sdk.rst

@@ -8,5 +8,6 @@ OpenTelemetry Python SDK
 
     resources
     trace
+    logs
     error_handler
     environment_variables

opentelemetry-sdk/src/opentelemetry/sdk/logs/severity.py

@@ -25,8 +25,7 @@ class SeverityNumber(enum.Enum):
     See the `Log Data Model`_ spec for more info and how to map the
     severity from source format to OTLP Model.
 
-    .. _Log Data Model:
-    https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-severitynumber
+    .. _Log Data Model: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-severitynumber
     """
 
     UNSPECIFIED = 0