Merge branch 'master' of https://github.com/open-telemetry/opentelemetry-python into labelset

Author: lzchen

.isort.cfg

@@ -14,3 +14,4 @@ line_length=79
 multi_line_output=3
 skip=target
 skip_glob=ext/opentelemetry-ext-jaeger/src/opentelemetry/ext/jaeger/gen/*
+known_first_party=opentelemetry

.travis.yml

@@ -7,12 +7,12 @@ python:
   - '3.5'
   - '3.6'
   - '3.7'
+  - '3.8'
   - 'pypy3.5'
-  - '3.8-dev'
 
-matrix:
-  allow_failures:
-    - python: '3.8-dev'
+#matrix:
+#  allow_failures:
+#    - python: '3.8-dev'
 
 install:
   - pip install tox-travis

CONTRIBUTING.md

@@ -19,7 +19,7 @@ If you are looking for someone to help you find a starting point and be a resour
 Gitter and find a buddy!
 
 1. Join [Gitter.im](https://gitter.im) and join our [chat room](https://gitter.im/open-telemetry/opentelemetry-python).
-2. Post in the room with an introduction to yourself, what area you are interested in (checks issues marked "Help Wanted"),
+2. Post in the room with an introduction to yourself, what area you are interested in (check issues marked "Help Wanted"),
 and say you are looking for a buddy. We will match you with someone who has experience in that area.
 
 Your OpenTelemetry buddy is your resource to talk to directly on all aspects of contributing to OpenTelemetry: providing
@@ -37,7 +37,7 @@ You can run:
   under multiple Python versions
 - `tox -e docs` to regenerate the API docs
 - `tox -e test-api` and `tox -e test-sdk` to run the API and SDK unit tests
-- `tox -e py37-test-api` to e.g. run the the API unit tests under a specific
+- `tox -e py37-test-api` to e.g. run the API unit tests under a specific
   Python version
 - `tox -e lint` to run lint checks on all code
 
@@ -115,7 +115,7 @@ It's especially valuable to read through the [library guidelines](https://github
 OpenTelemetry is an evolving specification, one where the desires and
 use cases are clear, but the method to satisfy those uses cases are not.
 
-As such, Contributions should provide functionality and behavior that 
+As such, contributions should provide functionality and behavior that
 conforms to the specification, but the interface and structure is flexible.
 
 It is preferable to have contributions follow the idioms of the language 

README.md

@@ -95,11 +95,15 @@ exporter.export([(counter, label_values)])
 exporter.shutdown()
 ```
 
-See the [API
-documentation](https://open-telemetry.github.io/opentelemetry-python/) for more
-detail, and the
-[opentelemetry-example-app](./examples/opentelemetry-example-app/README.rst)
-for a complete example.
+See the [API documentation](https://open-telemetry.github.io/opentelemetry-python/) for more detail, and the [examples folder](./examples) for a more sample code.
+
+## Extensions
+
+### Third-party exporters
+
+OpenTelemetry supports integration with the following third-party exporters.
+
+-  [Azure Monitor](https://github.com/microsoft/opentelemetry-exporters-python/tree/master/azure_monitor)
 
 ## Contributing
 
@@ -162,16 +166,16 @@ estimates, and subject to change.
 
 Future releases targets include:
 
-| Component                           | Version    | Target Date      |
-| ----------------------------------- | ---------- | ---------------- |
-| Zipkin Trace Exporter               | Alpha v0.3 | November 15 2019 |
-| W3C Correlation Context Propagation | Alpha v0.3 | November 15 2019 |
-| Support for Tags/Baggage            | Alpha v0.3 | November 15 2019 |
-| Metrics Aggregation                 | Alpha v0.3 | November 15 2019 |
-| gRPC Integrations                   | Alpha v0.3 | November 15 2019 |
-| Prometheus Metrics Exporter         | Alpha v0.3 | November 15 2019 |
+| Component                           | Version    | Target Date     |
+| ----------------------------------- | ---------- | --------------- |
+| Zipkin Trace Exporter               | Alpha v0.3 | December 6 2019 |
+| W3C Correlation Context Propagation | Alpha v0.3 | December 6 2019 |
+| Support for Tags/Baggage            | Alpha v0.3 | December 6 2019 |
+| Metrics Aggregation                 | Alpha v0.3 | December 6 2019 |
+| gRPC Integrations                   | Alpha v0.3 | December 6 2019 |
+| Prometheus Metrics Exporter         | Alpha v0.3 | December 6 2019 |
 
 | Component              | Version    | Target Date      |
 | ---------------------- | ---------- | ---------------- |
 | OpenCensus Bridge      | Alpha v0.4 | December 31 2019 |
-| Metrics SDK (Complete) | Alpha v0.4 | December 31 2019  |
+| Metrics SDK (Complete) | Alpha v0.4 | December 31 2019 |

docs/conf.py

@@ -13,7 +13,10 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath("../opentelemetry-api/src/"))
+sys.path[:0] = [
+    os.path.abspath("../opentelemetry-api/src/"),
+    os.path.abspath("../ext/opentelemetry-ext-opentracing-shim/src/"),
+]
 
 
 # -- Project information -----------------------------------------------------
@@ -47,7 +50,13 @@
     "sphinx.ext.githubpages",
 ]
 
-intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "opentracing": (
+        "https://opentracing-python.readthedocs.io/en/latest/",
+        None,
+    ),
+}
 
 # http://www.sphinx-doc.org/en/master/config.html#confval-nitpicky
 # Sphinx will warn about all references where the target cannot be found.

docs/index.rst

@@ -19,6 +19,7 @@ abstract types for OpenTelemetry implementations.
    opentelemetry.metrics
    opentelemetry.trace
    opentelemetry.util.loader
+   opentelemetry.ext.opentracing_shim
 
 
 Indices and tables

docs/opentelemetry.ext.opentracing_shim.rst

@@ -0,0 +1,8 @@
+opentelemetry.ext.opentracing_shim package
+==========================================
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.ext.opentracing_shim
+   :no-show-inheritance:

examples/README.md

@@ -0,0 +1,11 @@
+# Examples
+This folder contains various examples to demonstrate using OpenTelemetry.
+
+##### basic_tracer
+This example shows how to use OpenTelemetry to instrument an application - e.g. a batch job.
+
+##### http
+This example shows how to use [OpenTelemetryMiddleware](https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-ext-wsgi) and [requests](https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-ext-http-requests) integrations to instrument a client and a server.
+
+##### opentelemetry-example-app
+This package is a complete example of an application instrumented with OpenTelemetry.

examples/basic_tracer/README.md

@@ -0,0 +1,62 @@
+# Overview
+
+This example shows how to use OpenTelemetry to instrument a Python application - e.g. a batch job.
+It supports exporting spans either to the console or to [Jaeger](https://www.jaegertracing.io).
+
+## Installation
+
+```sh
+$ pip install opentelemetry-api opentelemetry-sdk
+```
+
+Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one)
+
+## Run the Application
+
+### Console
+
+* Run the sample
+
+```bash
+$ # from this directory
+$ python tracer.py
+```
+
+The output will be displayed at the console
+
+```bash
+AsyncRuntimeContext({'current_span': Span(name="baz", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x5611c1407e06e4d7, trace_state={}))})
+Span(name="baz", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x5611c1407e06e4d7, trace_state={}), kind=SpanKind.INTERNAL, parent=Span(name="bar", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1b9db0e0cc1a3f60, trace_state={})), start_time=2019-11-07T21:26:45.934412Z, end_time=2019-11-07T21:26:45.934567Z)
+Span(name="bar", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1b9db0e0cc1a3f60, trace_state={}), kind=SpanKind.INTERNAL, parent=Span(name="foo", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1d5d87441ec2f410, trace_state={})), start_time=2019-11-07T21:26:45.934396Z, end_time=2019-11-07T21:26:45.934576Z)
+Span(name="foo", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1d5d87441ec2f410, trace_state={}), kind=SpanKind.INTERNAL, parent=None, start_time=2019-11-07T21:26:45.934369Z, end_time=2019-11-07T21:26:45.934580Z)
+```
+
+
+### Jaeger
+
+* Run the sample
+
+```sh
+$ pip install opentelemetry-ext-jaeger
+$ # from this directory
+$ EXPORTER=jaeger python tracer.py
+```
+
+#### Jaeger UI
+
+Open the Jaeger UI in your browser [http://localhost:16686](http://localhost:16686)
+
+<p align="center"><img src="images/jaeger-ui.png?raw=true"/></p>
+Select `basic-service` under *Service Name* and click on *Find Traces*.
+
+Click on the trace to view its details.
+
+<p align="center"><img src="./images/jaeger-ui-detail.png?raw=true"/></p>
+
+## Useful links
+- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+- For more information on tracing in Python, visit: <https://github.com/open-telemetry/opentelemetry-python>
+
+## LICENSE
+
+Apache License 2.0

ext/opentelemetry-ext-azure-monitor/src/opentelemetry/ext/azure_monitor/__init__.py renamed to examples/basic_tracer/__init__.py

@@ -1,3 +1,4 @@
+# pylint: disable=C0103
 # Copyright 2019, OpenTelemetry Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -11,13 +12,3 @@
 # 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-ext-azure-monitor package provides integration with
-Microsoft Azure Monitor.
-"""
-
-from opentelemetry.ext.azure_monitor.trace import AzureMonitorSpanExporter
-from opentelemetry.ext.azure_monitor.version import __version__  # noqa
-
-__all__ = ["AzureMonitorSpanExporter"]

examples/basic_tracer/images/jaeger-ui-detail.png

@@ -0,0 +1,13 @@
+# Copyright 2019, 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.

examples/basic_tracer/images/jaeger-ui.png

@@ -0,0 +1,30 @@
+# Copyright 2019, 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.
+import os
+import subprocess
+import sys
+import unittest
+
+
+class TestBasicTracerExample(unittest.TestCase):
+    def test_basic_tracer(self):
+        dirpath = os.path.dirname(os.path.realpath(__file__))
+        test_script = "{}/../tracer.py".format(dirpath)
+        output = subprocess.check_output(
+            (sys.executable, test_script)
+        ).decode()
+
+        self.assertIn('name="foo"', output)
+        self.assertIn('name="bar"', output)
+        self.assertIn('name="baz"', output)

examples/basic_tracer/tests/__init__.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+#
+# Copyright 2019, 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.
+
+import os
+
+from opentelemetry import trace
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace import Tracer
+from opentelemetry.sdk.trace.export import (
+    BatchExportSpanProcessor,
+    ConsoleSpanExporter,
+)
+
+if os.getenv("EXPORTER") == "jaeger":
+    from opentelemetry.ext.jaeger import JaegerSpanExporter
+
+    exporter = JaegerSpanExporter(
+        service_name="basic-service",
+        agent_host_name="localhost",
+        agent_port=6831,
+    )
+else:
+    exporter = ConsoleSpanExporter()
+
+# The preferred tracer implementation must be set, as the opentelemetry-api
+# defines the interface with a no-op implementation.
+trace.set_preferred_tracer_implementation(lambda T: Tracer())
+tracer = trace.tracer()
+
+# SpanExporter receives the spans and send them to the target location.
+span_processor = BatchExportSpanProcessor(exporter)
+
+tracer.add_span_processor(span_processor)
+with tracer.start_as_current_span("foo"):
+    with tracer.start_as_current_span("bar"):
+        with tracer.start_as_current_span("baz"):
+            print(Context)