Merge branch 'master' into pymongo-command-type-coercion

open-telemetry · Sep 10, 2020 · 1109bf1 · 1109bf1
2 parents d9d5951 + 65ddc2d
commit 1109bf1
Show file tree

Hide file tree

Showing 91 changed files with 2,729 additions and 1,407 deletions.
diff --git a/.pylintrc b/.pylintrc
@@ -5,11 +5,11 @@
 # run arbitrary code.
 extension-pkg-whitelist=
 
-# Add files or directories to the blacklist. They should be base names, not
+# Add list of files or directories to be excluded. They should be base names, not
 # paths.
 ignore=CVS,gen,proto
 
-# Add files or directories matching the regex patterns to the blacklist. The
+# Add files or directories matching the regex patterns to be excluded. The
 # regex matches against base names, not paths.
 ignore-patterns=
 

diff --git a/README.md b/README.md
@@ -36,11 +36,13 @@
 
 ---
 
-## About this project
+## OpenTelemetry Python
 
-The Python [OpenTelemetry](https://opentelemetry.io/) client.
+The Python [OpenTelemetry](https://opentelemetry.io/) implementation.
 
-## Installation
+## Getting started
+
+OpenTelemetry's goal is to provide a single set of APIs to capture distributed traces and metrics from your application and send them to an observability platform. This project allows you to do just that for applications written in Python.
 
 This repository includes multiple installable packages. The `opentelemetry-api`
 package includes abstract classes and no-op implementations that comprise the OpenTelemetry API following
@@ -52,9 +54,6 @@ Libraries that produce telemetry data should only depend on `opentelemetry-api`,
 and defer the choice of the SDK to the application developer. Applications may
 depend on `opentelemetry-sdk` or another package that implements the API.
 
-**Please note** that this library is currently in _beta_, and shouldn't
-generally be used in production environments.
-
 The API and SDK packages are available on PyPI, and can installed via `pip`:
 
 ```sh
@@ -94,15 +93,11 @@ The online documentation is available at https://opentelemetry-python.readthedoc
 if you want to access the documentation for the latest version use
 https://opentelemetry-python.readthedocs.io/en/latest/.
 
-## Compatible Exporters
-
-See the [OpenTelemetry registry](https://opentelemetry.io/registry/?s=python) for a list of exporters available.
-
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md)
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-We meet weekly on Thursday, and the time of the meeting alternates between 9AM PT and 4PM PT. The meeting is subject to change depending on contributors' availability. Check the [OpenTelemetry community calendar](https://calendar.google.com/calendar/embed?src=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com) for specific dates.
+We meet weekly on Thursday at 9AM PT. The meeting is subject to change depending on contributors' availability. Check the [OpenTelemetry community calendar](https://calendar.google.com/calendar/embed?src=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com) for specific dates.
 
 Meetings take place via [Zoom video conference](https://zoom.us/j/6729396170).
 
@@ -134,78 +129,7 @@ Maintainers ([@open-telemetry/python-maintainers](https://github.com/orgs/open-t
   <img src="https://contributors-img.web.app/image?repo=open-telemetry/opentelemetry-python" />
 </a>
 
-## Release Schedule
-
-OpenTelemetry Python is under active development.
-
-The library is not yet _generally available_, and releases aren't guaranteed to
-conform to a specific version of the specification. Future releases will not
-attempt to maintain backwards compatibility with previous releases. Each alpha
-and beta release includes significant changes to the API and SDK packages,
-making them incompatible with each other.
-
-The [v0.1 alpha
-release](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v0.1.0)
-includes:
-
-- Tracing API
-- Tracing SDK
-- Metrics API
-- Metrics SDK (Partial)
-- W3C Trace Context Propagation
-- B3 Context Propagation
-- HTTP Integrations
-
-The [v0.2 alpha
-release](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v0.2.0)
-includes:
-
-- OpenTracing Bridge
-- Jaeger Trace Exporter
-- Trace Sampling
-
-The [v0.3 alpha
-release](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v0.3.0)
-includes:
-
-- Metrics Instruments and Labels
-- Flask Integration
-- PyMongo Integration
-
-The [v0.4 alpha
-release](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v0.4.0)
-includes:
-
-- Metrics MinMaxSumCount Aggregator
-- Context API
-- Full Metrics SDK Pipeline
-- Metrics STDOUT Exporter
-- Dbapi2 Integration
-- MySQL Integration
-- Psycopg2 Integration
-- Zipkin Exporter
-- Prometheus Metrics Exporter
-- New Examples and Improvements to Existing Examples
-
-The [v0.5 beta
-release](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v0.5.0)
-includes:
-
-- W3C Correlation Context Propagation
-- OpenTelemetry Collector Exporter Integration for both metrics and traces
-- Metrics SDK
-- Global configuration module
-- Documentation improvements
-
-The [v0.6 beta
-release](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v0.6.0)
-includes:
-
-- API changes and bugfixes
-- An autoinstrumentation package and updated Flask instrumentation
-- gRPC integration
-
-See the [project
-milestones](https://github.com/open-telemetry/opentelemetry-python/milestones)
-for details on upcoming releases. The dates and features described in issues
+## Project Status
+
+Project [boards](https://github.com/open-telemetry/opentelemetry-python/projects) and [milestones](https://github.com/open-telemetry/opentelemetry-python/milestones) can be found at the respective links. We try to keep these accurate and should be the best place to go for answers on project status. The dates and features described in issues
 and milestones are estimates, and subject to change.
diff --git a/dev-requirements.txt b/dev-requirements.txt
@@ -1,5 +1,5 @@
 pylint==2.4.4
-flake8==3.7.9
+flake8~=3.7
 isort~=4.3
 black>=19.3b0,==19.*
 mypy==0.770

diff --git a/docs/api/api.rst b/docs/api/api.rst
@@ -6,8 +6,8 @@ OpenTelemetry Python API
 .. toctree::
     :maxdepth: 1
 
+    baggage
     configuration
     context
-    correlationcontext
     metrics
     trace
diff --git a/docs/api/baggage.propagation.rst b/docs/api/baggage.propagation.rst
@@ -0,0 +1,7 @@
+opentelemetry.baggage.propagation package
+====================================================
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.baggage.propagation
diff --git a/docs/api/baggage.rst b/docs/api/baggage.rst
@@ -0,0 +1,14 @@
+opentelemetry.baggage package
+========================================
+
+Subpackages
+-----------
+
+.. toctree::
+
+   baggage.propagation
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.baggage
diff --git a/docs/api/correlationcontext.propagation.rst b/docs/api/correlationcontext.propagation.rst
diff --git a/docs/api/correlationcontext.rst b/docs/api/correlationcontext.rst
diff --git a/docs/api/trace.rst b/docs/api/trace.rst
@@ -6,7 +6,6 @@ Submodules
 
 .. toctree::
 
-   trace.sampling
    trace.status
    trace.span
 

diff --git a/docs/api/trace.sampling.rst b/docs/api/trace.sampling.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -103,17 +103,14 @@
     # with "class reference target not found: ObjectProxy".
     ("py:class", "ObjectProxy"),
     # TODO: Understand why sphinx is not able to find this local class
-    (
-        "py:class",
-        "opentelemetry.trace.propagation.httptextformat.HTTPTextFormat",
-    ),
+    ("py:class", "opentelemetry.trace.propagation.textmap.TextMapPropagator",),
     (
         "any",
-        "opentelemetry.trace.propagation.httptextformat.HTTPTextFormat.extract",
+        "opentelemetry.trace.propagation.textmap.TextMapPropagator.extract",
     ),
     (
         "any",
-        "opentelemetry.trace.propagation.httptextformat.HTTPTextFormat.inject",
+        "opentelemetry.trace.propagation.textmap.TextMapPropagator.inject",
     ),
 ]
 

diff --git a/docs/examples/datadog_exporter/server.py b/docs/examples/datadog_exporter/server.py
@@ -35,19 +35,19 @@
 )
 
 # append Datadog format for propagation to and from Datadog instrumented services
-global_httptextformat = propagators.get_global_httptextformat()
+global_textmap = propagators.get_global_textmap()
 if isinstance(
-    global_httptextformat, propagators.composite.CompositeHTTPPropagator
+    global_textmap, propagators.composite.CompositeHTTPPropagator
 ) and not any(
-    isinstance(p, DatadogFormat) for p in global_httptextformat._propagators
+    isinstance(p, DatadogFormat) for p in global_textmap._propagators
 ):
-    propagators.set_global_httptextformat(
+    propagators.set_global_textmap(
         propagators.composite.CompositeHTTPPropagator(
-            global_httptextformat._propagators + [DatadogFormat()]
+            global_textmap._propagators + [DatadogFormat()]
         )
     )
 else:
-    propagators.set_global_httptextformat(DatadogFormat())
+    propagators.set_global_textmap(DatadogFormat())
 
 tracer = trace.get_tracer(__name__)
 

diff --git a/docs/faq-and-cookbook.rst b/docs/faq-and-cookbook.rst
@@ -0,0 +1,27 @@
+Frequently Asked Questions and Cookbook
+=======================================
+
+This page answers frequently asked questions, and serves as a cookbook
+for common scenarios.
+
+Create a new span
+-----------------
+
+.. code-block:: python
+
+    from opentelemetry import trace
+
+    tracer = trace.get_tracer(__name__)
+    with tracer.start_as_current_span("print") as span:
+        print("foo")
+        span.set_attribute("printed_string", "foo")
+
+Getting and modifying a span
+----------------------------
+
+.. code-block:: python
+
+    from opentelemetry import trace
+
+    current_span = trace.get_current_span()
+    current_span.set_attribute("hometown", "seattle")
diff --git a/docs/getting-started.rst b/docs/getting-started.rst
@@ -174,7 +174,7 @@ Now run the above script, hit the root url (http://localhost:5000/) a few times,
    python flask_example.py
 
 
-Configure Your HTTP Propagator (b3, CorrelationContext)
+Configure Your HTTP Propagator (b3, Baggage)
 -------------------------------------------------------
 
 A major feature of distributed tracing is the ability to correlate a trace across
@@ -194,7 +194,7 @@ an example using Zipkin's `b3 propagation <https://github.com/openzipkin/b3-prop
     from opentelemetry import propagators
     from opentelemetry.sdk.trace.propagation.b3_format import B3Format
 
-    propagators.set_global_httptextformat(B3Format())
+    propagators.set_global_textmap(B3Format())
 
 
 Adding Metrics

diff --git a/docs/getting_started/tests/test_flask.py b/docs/getting_started/tests/test_flask.py
@@ -18,6 +18,8 @@
 from time import sleep
 
 import requests
+from requests.adapters import HTTPAdapter
+from requests.packages.urllib3.util.retry import Retry
 
 
 class TestFlask(unittest.TestCase):
@@ -27,17 +29,20 @@ def test_flask(self):
         server = subprocess.Popen(
             [sys.executable, server_script], stdout=subprocess.PIPE,
         )
-        sleep(1)
+        retry_strategy = Retry(total=10, backoff_factor=1)
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        http = requests.Session()
+        http.mount("http://", adapter)
 
         try:
-            result = requests.get("http://localhost:5000")
+            result = http.get("http://localhost:5000")
             self.assertEqual(result.status_code, 200)
 
             sleep(0.1)
         finally:
             server.terminate()
 
         output = str(server.stdout.read())
-        self.assertIn('"name": "HTTP get"', output)
+        self.assertIn('"name": "HTTP GET"', output)
         self.assertIn('"name": "example-request"', output)
         self.assertIn('"name": "hello"', output)
diff --git a/docs/index.rst b/docs/index.rst
@@ -11,8 +11,8 @@ The Python `OpenTelemetry <https://opentelemetry.io/>`_ client.
 This documentation describes the :doc:`opentelemetry-api <api/api>`,
 :doc:`opentelemetry-sdk <sdk/sdk>`, and several `integration packages <#integrations>`_.
 
-**Please note** that this library is currently in alpha, and shouldn't be
-used in production environments.
+**Please note** that this library is currently in _beta_, and shouldn't
+generally be used in production environments.
 
 Installation
 ------------
@@ -62,6 +62,7 @@ install <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>
     :name: getting-started
 
     getting-started
+    faq-and-cookbook
 
 .. toctree::
     :maxdepth: 1

diff --git a/docs/instrumentation/asgi/asgi.rst b/docs/instrumentation/asgi/asgi.rst
@@ -1,8 +1,7 @@
-OpenTelemetry asgi Instrumentation
-===================================
+.. include:: ../../../instrumentation/opentelemetry-instrumentation-asgi/README.rst
 
-Module contents
----------------
+API
+---
 
 .. automodule:: opentelemetry.instrumentation.asgi
     :members:

diff --git a/docs/sdk/trace.rst b/docs/sdk/trace.rst
@@ -7,6 +7,7 @@ Submodules
 .. toctree::
 
    trace.export
+   trace.sampling
    util.instrumentation
 
 .. automodule:: opentelemetry.sdk.trace

diff --git a/docs/sdk/trace.sampling.rst b/docs/sdk/trace.sampling.rst
@@ -0,0 +1,7 @@
+opentelemetry.sdk.trace.sampling
+==========================================
+
+.. automodule:: opentelemetry.sdk.trace.sampling
+    :members:
+    :undoc-members:
+    :show-inheritance: