Merge branch 'main' into b3-multi-propagator

open-telemetry · May 7, 2021 · 3eccb3e · 3eccb3e
2 parents 50a7b7f + 64d0426
commit 3eccb3e
Show file tree

Hide file tree

Showing 18 changed files with 156 additions and 39 deletions.
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/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/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.

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")),
 )

diff --git a/docs/index.rst b/docs/index.rst
@@ -72,31 +72,31 @@ install <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>
 
 .. toctree::
     :maxdepth: 1
-    :caption: OpenTelemetry Python Packages
+    :caption: Core Packages
     :name: packages
 
     api/api
     sdk/sdk
 
 .. toctree::
     :maxdepth: 2
-    :caption: OpenTelemetry Exporters
+    :caption: Exporters
     :name: exporters
     :glob:
 
     exporter/**
 
 .. toctree::
     :maxdepth: 2
-    :caption: OpenTelemetry Shims
+    :caption: Shims
     :name: Shims
     :glob:
 
     shim/**
 
 .. toctree::
     :maxdepth: 1
-    :caption: OpenTelemetry Python Performance
+    :caption: Performance
     :name: performance-tests
     :glob:
 

diff --git a/opentelemetry-api/src/opentelemetry/util/_time.py b/opentelemetry-api/src/opentelemetry/util/_time.py
@@ -18,7 +18,7 @@
 if version_info.minor < 7:
     getLogger(__name__).warning(  # pylint: disable=logging-not-lazy
         "You are using Python 3.%s. This version does not support timestamps "
-        "with nanosecond precision and the Opentelemetry SDK will use "
+        "with nanosecond precision and the OpenTelemetry SDK will use "
         "millisecond precision instead. Please refer to PEP 546 for more "
         "information. Please upgrade to Python 3.7 or newer to use nanosecond "
         "precision." % version_info.minor

diff --git a/opentelemetry-distro/README.rst b/opentelemetry-distro/README.rst
@@ -14,9 +14,10 @@ Installation
     pip install opentelemetry-distro
 
 
-This package provides entrypoints to configure OpenTelemetry
+This package provides entrypoints to configure OpenTelemetry.
 
 References
 ----------
 
 * `OpenTelemetry Project <https://opentelemetry.io/>`_
+* `Example using opentelemetry-distro <https://opentelemetry-python.readthedocs.io/en/latest/examples/distro/README.html>`_