Merge branch 'main' of https://github.com/open-telemetry/opentelemetr…

…y-python into otlp
open-telemetry · May 10, 2021 · f2fe921 · f2fe921
2 parents d330346 + cc18b73
commit f2fe921
Show file tree

Hide file tree

Showing 42 changed files with 541 additions and 113 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,13 +6,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased](https://github.com/open-telemetry/opentelemetry-python/compare/v1.1.0...HEAD)
 
+### Changed
+- Include span parent in Jaeger gRPC export as `CHILD_OF` reference
+  ([#1809])(https://github.com/open-telemetry/opentelemetry-python/pull/1809)
+
 ### Added
 - Added example for running Django with auto instrumentation.
   ([#1803](https://github.com/open-telemetry/opentelemetry-python/pull/1803))
+- Added support for OTEL_SERVICE_NAME.
+  ([#1829](https://github.com/open-telemetry/opentelemetry-python/pull/1829))
 
 ### Changed
 - Fixed OTLP gRPC exporter silently failing if scheme is not specified in endpoint.
   ([#1806](https://github.com/open-telemetry/opentelemetry-python/pull/1806))
+- Rename CompositeHTTPPropagator to CompositePropagator as per specification.
+  ([#1807](https://github.com/open-telemetry/opentelemetry-python/pull/1807))
+- Propagators use the root context as default for `extract` and do not modify
+  the context if extracting from carrier does not work.
+  ([#1811](https://github.com/open-telemetry/opentelemetry-python/pull/1811))
+- Improve warning when failing to decode byte attribute
+  ([#1810](https://github.com/open-telemetry/opentelemetry-python/pull/1810))
+- Fixed inconsistency in parent_id formatting from the ConsoleSpanExporter
+  ([#1833](https://github.com/open-telemetry/opentelemetry-python/pull/1833))
 
 ### Removed
 - Moved `opentelemetry-instrumentation` to contrib repository.

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -19,7 +19,7 @@ This is the main repo for OpenTelemetry Python. Nevertheless, there are other re
 Please take a look at this list first, your contributions may belong in one of these repos better:
 
 1. [OpenTelemetry Contrib](https://github.com/open-telemetry/opentelemetry-python-contrib): Instrumentations for third-party
-   libraries and frameworks. There is an ongoing effort to migrate into the Opentelemetry Contrib repo some of the existing
+   libraries and frameworks. There is an ongoing effort to migrate into the OpenTelemetry Contrib repo some of the existing
    programmatic instrumentations that are now in the `ext` directory in the main OpenTelemetry repo. Please ask in the Slack
    channel (see below) for guidance if you want to contribute with these instrumentations.
 

diff --git a/README.md b/README.md
@@ -132,7 +132,6 @@ Approvers ([@open-telemetry/python-approvers](https://github.com/orgs/open-telem
 
 - [Aaron Abbott](https://github.com/aabmass), Google
 - [Diego Hurtado](https://github.com/ocelotl)
-- [Hector Hernandez](https://github.com/hectorhdzg), Microsoft
 - [Owais Lone](https://github.com/owais), Splunk
 - [Srikanth Chekuri](https://github.com/lonewolf3739)
 

diff --git a/dev-requirements.txt b/dev-requirements.txt
@@ -4,9 +4,9 @@ isort~=5.8
 black~=20.8b1
 httpretty~=1.0
 mypy==0.812
-sphinx~=2.1
-sphinx-rtd-theme~=0.4
-sphinx-autodoc-typehints~=1.10.2
+sphinx~=3.5.4
+sphinx-rtd-theme~=0.5
+sphinx-autodoc-typehints
 pytest>=6.0
 pytest-cov>=2.8
 readme-renderer~=24.0

diff --git a/docs-requirements.txt b/docs-requirements.txt
@@ -1,6 +1,8 @@
-sphinx~=2.4
-sphinx-rtd-theme~=0.4
+sphinx~=3.5.4
+sphinx-rtd-theme~=0.5
 sphinx-autodoc-typehints
+# used to generate docs for the website
+sphinx-jekyll-builder
 
 # Need to install the api/sdk in the venv for autodoc. Modifying sys.path
 # doesn't work for pkg_resources.

diff --git a/docs/conf.py b/docs/conf.py
@@ -125,7 +125,15 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "examples/fork-process-model/flask-gunicorn",
+    "examples/fork-process-model/flask-uwsgi",
+    "examples/error_handler/error_handler_0",
+    "examples/error_handler/error_handler_1",
+]
 
 autodoc_default_options = {
     "members": True,

diff --git a/docs/examples/auto-instrumentation/README.rst b/docs/examples/auto-instrumentation/README.rst
@@ -45,7 +45,7 @@ Manually instrumented server
             return "served"
 
 Server not instrumented manually
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``server_uninstrumented.py``
 
@@ -57,7 +57,7 @@ Server not instrumented manually
         return "served"
 
 Prepare
------------
+-------
 
 Execute the following example in a separate virtual environment.
 Run the following commands to prepare for auto-instrumentation:
@@ -69,7 +69,7 @@ Run the following commands to prepare for auto-instrumentation:
     $ source auto_instrumentation/bin/activate
 
 Install
-------------
+-------
 
 Run the following commands to install the appropriate packages. The
 ``opentelemetry-instrumentation`` package provides several 
@@ -90,7 +90,7 @@ a server as well as the process of executing an automatically
 instrumented server.
 
 Execute a manually instrumented server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Execute the server in two separate consoles, one to run each of the 
 scripts that make up this example:
@@ -145,7 +145,7 @@ similar to the following example:
     }
 
 Execute an automatically instrumented server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Stop the execution of ``server_instrumented.py`` with ``ctrl + c``
 and run the following command instead:
@@ -208,7 +208,7 @@ You can see that both outputs are the same because automatic instrumentation doe
 exactly what manual instrumentation does.
 
 Instrumentation while debugging
-===============================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The debug mode can be enabled in the Flask app like this:
 
@@ -226,3 +226,11 @@ reloader. To run instrumentation while the debug mode is enabled, set the
 
     if __name__ == "__main__":
         app.run(port=8082, debug=True, use_reloader=False)
+
+
+Additional resources 
+~~~~~~~~~~~~~~~~~~~~
+
+In order to send telemetry to an OpenTelemetry Collector without doing any
+additional configuration, read about the `OpenTelemetry Distro <../distro/README.html>`_
+package.
diff --git a/docs/examples/basic_context/README.rst b/docs/examples/basic_context/README.rst
@@ -1,14 +1,11 @@
 Basic Context
 =============
 
-These examples show how context is propagated through Spans in OpenTelemetry.
-
-There are three different examples:
+These examples show how context is propagated through Spans in OpenTelemetry. There are three different
+examples:
 
 * implicit_context: Shows how starting a span implicitly creates context.
-
 * child_context: Shows how context is propagated through child spans.
-
 * async_context: Shows how context can be shared in another coroutine.
 
 The source files of these examples are available :scm_web:`here <docs/examples/basic_context/>`.

diff --git a/docs/examples/basic_tracer/README.rst b/docs/examples/basic_tracer/README.rst
@@ -1,12 +1,9 @@
 Basic Trace
 ===========
 
-These examples show how to use OpenTelemetry to create and export Spans.
-
-There are two different examples:
+These examples show how to use OpenTelemetry to create and export Spans. There are two different examples:
 
 * basic_trace: Shows how to configure a SpanProcessor and Exporter, and how to create a tracer and span.
-
 * resources: Shows how to add resource information to a Provider.
 
 The source files of these examples are available :scm_web:`here <docs/examples/basic_tracer/>`.

diff --git a/docs/examples/datadog_exporter/README.rst b/docs/examples/datadog_exporter/README.rst
@@ -1,5 +1,5 @@
-Datadog Exporter Example
-========================
+Datadog Exporter
+================
 
 These examples show how to use OpenTelemetry to send tracing data to Datadog.
 

diff --git a/docs/examples/datadog_exporter/server.py b/docs/examples/datadog_exporter/server.py
@@ -21,7 +21,7 @@
 )
 from opentelemetry.exporter.datadog.propagator import DatadogFormat
 from opentelemetry.propagate import get_global_textmap, set_global_textmap
-from opentelemetry.propagators.composite import CompositeHTTPPropagator
+from opentelemetry.propagators.composite import CompositePropagator
 from opentelemetry.sdk.trace import TracerProvider
 
 app = Flask(__name__)
@@ -38,13 +38,11 @@
 
 # append Datadog format for propagation to and from Datadog instrumented services
 global_textmap = get_global_textmap()
-if isinstance(global_textmap, CompositeHTTPPropagator) and not any(
+if isinstance(global_textmap, CompositePropagator) and not any(
     isinstance(p, DatadogFormat) for p in global_textmap._propagators
 ):
     set_global_textmap(
-        CompositeHTTPPropagator(
-            global_textmap._propagators + [DatadogFormat()]
-        )
+        CompositePropagator(global_textmap._propagators + [DatadogFormat()])
     )
 else:
     set_global_textmap(DatadogFormat())

diff --git a/docs/examples/distro/README.rst b/docs/examples/distro/README.rst
@@ -0,0 +1,104 @@
+OpenTelemetry Distro
+====================
+
+In order to make using OpenTelemetry and auto-instrumentation as quick as possible without sacrificing flexibility,
+OpenTelemetry distros provide a mechanism to automatically configure some of the more common options for users. By
+harnessing their power, users of OpenTelemetry can configure the components as they need. The ``opentelemetry-distro``
+package provides some defaults to users looking to get started, it configures:
+
+- the SDK TracerProvider
+- a BatchSpanProcessor
+- the OTLP ``SpanExporter`` to send data to an OpenTelemetry collector
+
+The package also provides a starting point for anyone interested in producing an alternative distro. The
+interfaces implemented by the package are loaded by the auto-instrumentation via the ``opentelemetry_distro``
+and ``opentelemetry_configurator`` entry points to configure the application before any other code is
+executed.
+
+In order to automatically export data from OpenTelemetry to the OpenTelemetry collector, installing the
+package will setup all the required entry points.
+
+.. code:: sh
+
+    $ pip install opentelemetry-distro[otlp] opentelemetry-instrumentation
+
+Start the Collector locally to see data being exported. Write the following file:
+
+.. code-block:: yaml
+
+    # /tmp/otel-collector-config.yaml
+    receivers:
+        otlp:
+            protocols:
+                grpc:
+                http:
+    exporters:
+        logging:
+            loglevel: debug
+    processors:
+        batch:
+    service:
+        pipelines:
+            traces:
+                receivers: [otlp]
+                exporters: [logging]
+                processors: [batch]
+
+Then start the Docker container:
+
+.. code-block:: sh
+
+    docker run -p 4317:4317 \
+        -v /tmp/otel-collector-config.yaml:/etc/otel-collector-config.yaml \
+        otel/opentelemetry-collector:latest \
+        --config=/etc/otel-collector-config.yaml
+
+The following code will create a span with no configuration.
+
+.. code:: python
+
+    # no_configuration.py
+    from opentelemetry import trace
+
+    with trace.get_tracer(__name__).start_as_current_span("foo"):
+        with trace.get_tracer(__name__).start_as_current_span("bar"):
+            print("baz")
+
+Lastly, run the ``no_configuration.py`` with the auto-instrumentation:
+
+.. code-block:: sh
+
+    $ opentelemetry-instrument python no_configuration.py
+
+The resulting span will appear in the output from the collector and look similar to this:
+
+.. code-block:: sh
+
+               Resource labels:
+                    -> telemetry.sdk.language: STRING(python)
+                    -> telemetry.sdk.name: STRING(opentelemetry)
+                    -> telemetry.sdk.version: STRING(1.1.0)
+                    -> service.name: STRING(unknown_service)
+               InstrumentationLibrarySpans #0
+               InstrumentationLibrary __main__
+               Span #0
+                   Trace ID       : db3c99e5bfc50ef8be1773c3765e8845
+                   Parent ID      : 0677126a4d110cb8
+                   ID             : 3163b3022808ed1b
+                   Name           : bar
+                   Kind           : SPAN_KIND_INTERNAL
+                   Start time     : 2021-05-06 22:54:51.23063 +0000 UTC
+                   End time       : 2021-05-06 22:54:51.230684 +0000 UTC
+                   Status code    : STATUS_CODE_UNSET
+                   Status message :
+               Span #1
+                   Trace ID       : db3c99e5bfc50ef8be1773c3765e8845
+                   Parent ID      :
+                   ID             : 0677126a4d110cb8
+                   Name           : foo
+                   Kind           : SPAN_KIND_INTERNAL
+                   Start time     : 2021-05-06 22:54:51.230549 +0000 UTC
+                   End time       : 2021-05-06 22:54:51.230706 +0000 UTC
+                   Status code    : STATUS_CODE_UNSET
+                   Status message :
+
diff --git a/docs/examples/django/README.rst b/docs/examples/django/README.rst
@@ -1,5 +1,5 @@
-OpenTelemetry Django Instrumentation Example
-============================================
+Django Instrumentation
+======================
 
 This shows how to use ``opentelemetry-instrumentation-django`` to automatically instrument a
 Django app.
@@ -142,4 +142,4 @@ References
 
 * `Django <https://djangoproject.com/>`_
 * `OpenTelemetry Project <https://opentelemetry.io/>`_
-* `OpenTelemetry Django extension <https://github.com/open-telemetry/opentelemetry-python-contib/tree/main/instrumentation/opentelemetry-instrumentation-django>`_
+* `OpenTelemetry Django extension <https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-django>`_
diff --git a/docs/examples/opencensus-exporter-tracer/README.rst b/docs/examples/opencensus-exporter-tracer/README.rst
@@ -1,5 +1,5 @@
-OpenTelemetry Collector Tracer OpenCensus Exporter Example
-==========================================================
+OpenCensus Exporter
+===================
 
 This example shows how to use the OpenCensus Exporter to export traces to the
 OpenTelemetry collector.

diff --git a/docs/examples/opentracing/README.rst b/docs/examples/opentracing/README.rst
@@ -1,5 +1,5 @@
-OpenTracing Shim Example
-==========================
+OpenTracing Shim
+================
 
 This example shows how to use the :doc:`opentelemetry-opentracing-shim
 package <../../shim/opentracing_shim/opentracing_shim>`

diff --git a/docs/exporter/jaeger/jaeger.rst b/docs/exporter/jaeger/jaeger.rst
@@ -1,4 +1,4 @@
-Opentelemetry Jaeger Exporters
+OpenTelemetry Jaeger Exporters
 ==============================
 
 .. automodule:: opentelemetry.exporter.jaeger

diff --git a/docs/exporter/otlp/otlp.rst b/docs/exporter/otlp/otlp.rst
@@ -1,4 +1,4 @@
-Opentelemetry OTLP Exporters
+OpenTelemetry OTLP Exporters
 ============================
 
 .. automodule:: opentelemetry.exporter.otlp

diff --git a/docs/getting_started/otlpcollector_example.py b/docs/getting_started/otlpcollector_example.py
@@ -24,7 +24,7 @@
 
 span_exporter = OTLPSpanExporter(
     # optional
-    # endpoint:="myCollectorURL:4317",
+    # endpoint="myCollectorURL:4317",
     # credentials=ChannelCredentials(credentials),
     # headers=(("metadata", "metadata")),
 )