Merge branch 'master' into majorgreys/datadog-resource-target

.circleci/config.yml

@@ -0,0 +1,57 @@
+version: 2.1
+
+executors:
+  python38:
+    docker:
+      - image: circleci/python:3.8
+
+commands:
+  setup_tox:
+    description: "Install tox"
+    steps:
+      - run: pip install -U tox-factor
+
+  restore_tox_cache:
+    description: "Restore .tox directory from previous runs for faster installs"
+    steps:
+      - restore_cache:
+          # In the cache key:
+          #   - .Environment.CIRCLE_JOB: We do separate tox environments by job name, so caching and restoring is
+          #                              much faster.
+          key: tox-cache-{{ .Environment.CIRCLE_JOB }}-{{ checksum "tox.ini" }}-{{ checksum "dev-requirements.txt" }}
+
+  save_tox_cache:
+    description: "Save .tox directory into cache for faster installs next time"
+    steps:
+      - save_cache:
+          # In the cache key:
+          #   - .Environment.CIRCLE_JOB: We do separate tox environments by job name, so caching and restoring is
+          #                              much faster.
+          key: tox-cache-{{ .Environment.CIRCLE_JOB }}-{{ checksum "tox.ini" }}-{{ checksum "dev-requirements.txt" }}
+          paths:
+            - ".tox"
+
+jobs:
+  docs:
+    executor: python38
+    steps:
+      - checkout
+      - setup_tox
+      - restore_tox_cache
+      - run: tox -e docs
+      - save_tox_cache
+
+  lint:
+    executor: python38
+    steps:
+      - checkout
+      - setup_tox
+      - restore_tox_cache
+      - run: tox -e lint
+      - save_tox_cache
+
+workflows:
+  main:
+    jobs:
+      - docs
+      - lint

dev-requirements.txt

@@ -8,6 +8,4 @@ sphinx-rtd-theme~=0.4
 sphinx-autodoc-typehints~=1.10.2
 pytest!=5.2.3
 pytest-cov>=2.8
-readme-renderer~=24.0
-httpretty~=1.0
-opentracing~=2.2.0
+readme-renderer~=24.0

docs-requirements.txt

@@ -14,7 +14,9 @@ mysql-connector-python~=8.0
 opentracing~=2.2.0
 prometheus_client>=0.5.0,<1.0.0
 psycopg2-binary>=2.7.3.1
+pymemcache~=1.3
 pymongo~=3.1
+pyramid>=1.7
 redis>=2.6
 sqlalchemy>=1.0
 thrift>=0.10.0
@@ -24,3 +26,4 @@ boto~=2.0
 google-cloud-trace >=0.23.0
 google-cloud-monitoring>=0.36.0
 botocore~=1.0
+starlette~=0.13

docs/examples/cloud_monitoring/README.rst

@@ -22,9 +22,9 @@ To use this exporter you first need to:
 
 * Run example
 
-.. code-block:: sh
-
-    python basic_metrics.py
+.. literalinclude:: basic_metrics.py
+    :language: python
+    :lines: 1-
 
 Viewing Output
 --------------------------

docs/examples/cloud_trace_exporter/README.rst

@@ -8,9 +8,10 @@ Basic Example
 -------------
 
 To use this exporter you first need to:
-    * A Google Cloud project. You can `create one here. <https://console.cloud.google.com/projectcreate>`_
-    * Enable Cloud Trace API (aka StackDriver Trace API) in the project `here. <https://console.cloud.google.com/apis/library?q=cloud_trace>`_
-    * Enable `Default Application Credentials. <https://developers.google.com/identity/protocols/application-default-credentials>`_
+    * A Google Cloud project. You can `create one here <https://console.cloud.google.com/projectcreate>`_.
+    * Enable Cloud Trace API (listed in the Cloud Console as Stackdriver Trace API) in the project `here <https://console.cloud.google.com/apis/library?q=cloud%20trace&filter=visibility:public>`_.
+      * If the page says "API Enabled" then you're done! No need to do anything.
+    * Enable Default Application Credentials by creating setting `GOOGLE_APPLICATION_CREDENTIALS <https://cloud.google.com/docs/authentication/getting-started>`_ or by `installing gcloud sdk <https://cloud.google.com/sdk/install>`_ and calling ``gcloud auth application-default login``.
 
 * Installation
 
@@ -20,15 +21,59 @@ To use this exporter you first need to:
     pip install opentelemetry-sdk
     pip install opentelemetry-exporter-cloud-trace
 
-* Run example
+* Run an example locally
 
-.. code-block:: sh
-
-    python basic_trace.py
+.. literalinclude:: basic_trace.py
+    :language: python
+    :lines: 1-
 
 Checking Output
 --------------------------
 
 After running any of these examples, you can go to `Cloud Trace overview <https://console.cloud.google.com/traces/list>`_ to see the results.
 
-* `More information about exporters in general <https://opentelemetry-python.readthedocs.io/en/stable/getting-started.html#configure-exporters-to-emit-spans-elsewhere>`_
+
+Further Reading
+--------------------------
+
+* `More information about exporters in general <https://opentelemetry-python.readthedocs.io/en/stable/getting-started.html#configure-exporters-to-emit-spans-elsewhere>`_
+
+Troubleshooting
+--------------------------
+
+Running basic_trace.py hangs:
+#############################
+    * Make sure you've setup Application Default Credentials. Either run ``gcloud auth application-default login`` or set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to be a path to a service account token file.
+
+Getting error ``google.api_core.exceptions.ResourceExhausted: 429 Resource has been exhausted``:
+################################################################################################
+    * Check that you've enabled the `Cloud Trace (Stackdriver Trace) API <https://console.cloud.google.com/apis/library?q=cloud%20trace&filter=visibility:public>`_
+
+bash: pip: command not found:
+#############################
+    * `Install pip <https://cloud.google.com/python/setup#installing_python>`_
+    * If your machine uses python2 by default, pip will also be the python2 version. Try using ``pip3`` instead of ``pip``.
+
+pip install is hanging
+######################
+Try upgrading pip
+
+.. code-block:: sh
+
+    pip install --upgrade pip
+
+``pip install grcpio`` has been known to hang when you aren't using an upgraded version.
+
+ImportError: No module named opentelemetry
+##########################################
+Make sure you are using python3. If
+
+.. code-block:: sh
+
+    python --version
+
+returns ``Python 2.X.X`` try calling
+
+.. code-block:: sh
+
+    python3 basic_trace.py

docs/examples/datadog_exporter/README.rst

@@ -32,10 +32,15 @@ Basic Example
 
 .. code-block:: sh
 
-    python datadog_exporter.py
+    python basic_example.py
 
-Auto-Instrumention Example
---------------------------
+
+.. code-block:: sh
+
+    python basic_example.py
+
+Distributed Example
+-------------------
 
 * Installation
 
@@ -79,3 +84,12 @@ Auto-Instrumention Example
 .. code-block:: sh
 
     opentelemetry-instrument python client.py error
+
+* Run Datadog instrumented client
+
+The OpenTelemetry instrumented server is set up with propagation of Datadog trace context.
+
+.. code-block:: sh
+
+    pip install ddtrace
+    ddtrace-run python datadog_client.py testing

docs/examples/datadog_exporter/datadog_exporter.py → docs/examples/datadog_exporter/basic_example.py

@@ -31,6 +31,7 @@
 span_processor = DatadogExportSpanProcessor(exporter)
 trace.get_tracer_provider().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"):

docs/examples/datadog_exporter/datadog_client.py

@@ -0,0 +1,23 @@
+# Copyright The 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.
+
+from sys import argv
+
+import requests
+
+requested = requests.get(
+    "http://localhost:8082/server_request", params={"param": argv[1]}
+)
+assert requested.status_code == 200
+print(requested.text)

docs/examples/datadog_exporter/server.py

@@ -14,11 +14,12 @@
 
 from flask import Flask, request
 
-from opentelemetry import trace
+from opentelemetry import propagators, trace
 from opentelemetry.ext.datadog import (
     DatadogExportSpanProcessor,
     DatadogSpanExporter,
 )
+from opentelemetry.ext.datadog.propagator import DatadogFormat
 from opentelemetry.sdk.trace import TracerProvider
 
 app = Flask(__name__)
@@ -33,6 +34,21 @@
     )
 )
 
+# append Datadog format for propagation to and from Datadog instrumented services
+global_httptextformat = propagators.get_global_httptextformat()
+if isinstance(
+    global_httptextformat, propagators.composite.CompositeHTTPPropagator
+) and not any(
+    isinstance(p, DatadogFormat) for p in global_httptextformat._propagators
+):
+    propagators.set_global_httptextformat(
+        propagators.composite.CompositeHTTPPropagator(
+            global_httptextformat._propagators + [DatadogFormat()]
+        )
+    )
+else:
+    propagators.set_global_httptextformat(DatadogFormat())
+
 tracer = trace.get_tracer(__name__)
 
 

docs/examples/opentelemetry-example-app/setup.cfg

@@ -0,0 +1,62 @@
+# Copyright The 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.
+#
+[metadata]
+name = opentelemetry-example-app
+description = OpenTelemetry Example App
+long_description = file: README.rst
+long_description_content_type = text/x-rst
+author = OpenTelemetry Authors
+author_email = cncf-opentelemetry-contributors@lists.cncf.io
+url = https://github.com/open-telemetry/opentelemetry-python/tree/master/opentelemetry-example-app
+platforms = any
+license = Apache-2.0
+classifiers =
+    Development Status :: 4 - Beta
+    Intended Audience :: Developers
+    License :: OSI Approved :: Apache Software License
+    Programming Language :: Python
+    Programming Language :: Python :: 3
+    Programming Language :: Python :: 3.4
+    Programming Language :: Python :: 3.5
+    Programming Language :: Python :: 3.6
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+
+[options]
+python_requires = >=3.4
+package_dir=
+    =src
+packages = find_namespace:
+zip_safe = False
+include_package_data = True
+install_requires = 
+    typing; python_version<'3.5'
+    opentelemetry-api == 0.10.dev0
+    opentelemetry-sdk == 0.10.dev0
+    opentelemetry-ext-requests == 0.10.dev0
+    opentelemetry-ext-flask == 0.10.dev0
+    flask
+    requests
+    protobuf~=3.11
+
+[options.packages.find]
+where = src
+include = opentelemetry_example_app
+
+[options.entry_points]
+opentelemetry_meter_provider =
+    sdk_meter_provider = opentelemetry.sdk.metrics:MeterProvider
+opentelemetry_tracer_provider =
+    sdk_tracer_provider = opentelemetry.sdk.trace:TracerProvider

docs/examples/opentelemetry-example-app/setup.py

@@ -11,44 +11,16 @@
 # 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 setuptools
 
-setuptools.setup(
-    name="opentelemetry-example-app",
-    version="0.9.dev0",
-    author="OpenTelemetry Authors",
-    author_email="cncf-opentelemetry-contributors@lists.cncf.io",
-    classifiers=[
-        "Development Status :: 4 - Beta",
-        "Intended Audience :: Developers",
-        "License :: OSI Approved :: Apache Software License",
-        "Programming Language :: Python",
-        "Programming Language :: Python :: 3",
-        "Programming Language :: Python :: 3.4",
-        "Programming Language :: Python :: 3.5",
-        "Programming Language :: Python :: 3.6",
-        "Programming Language :: Python :: 3.7",
-    ],
-    description="OpenTelemetry Python API",
-    include_package_data=True,
-    long_description=open("README.rst").read(),
-    install_requires=[
-        "typing; python_version<'3.5'",
-        "opentelemetry-api",
-        "opentelemetry-sdk",
-        "opentelemetry-ext-requests",
-        "opentelemetry-ext-flask",
-        "flask",
-        "requests",
-        "protobuf~=3.11",
-    ],
-    license="Apache-2.0",
-    package_dir={"": "src"},
-    packages=setuptools.find_namespace_packages(where="src"),
-    url=(
-        "https://github.com/open-telemetry/opentelemetry-python"
-        "/tree/master/opentelemetry-example-app"
-    ),
-    zip_safe=False,
+BASE_DIR = os.path.dirname(__file__)
+VERSION_FILENAME = os.path.join(
+    BASE_DIR, "src", "opentelemetry_example_app", "version.py"
 )
+PACKAGE_INFO = {}
+with open(VERSION_FILENAME) as f:
+    exec(f.read(), PACKAGE_INFO)
+
+setuptools.setup(version=PACKAGE_INFO["__version__"],)