Adding opentelemetry-distro package and entrypoint

CHANGELOG.md

@@ -24,6 +24,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `opentelemetry-sdk` package now registers an entrypoint `opentelemetry_configurator`
   to allow `opentelemetry-instrument` to load the configuration for the SDK
   ([#1420](https://github.com/open-telemetry/opentelemetry-python/pull/1420))
+- Adding `opentelemetry-distro` package to add default configuration for
+  span exporter to OTLP
+  ([#1482](https://github.com/open-telemetry/opentelemetry-python/pull/1482))
 
 ## [0.16b1](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v0.16b1) - 2020-11-26
 ### Added

eachdist.ini

@@ -9,6 +9,7 @@ sortfirst=
     opentelemetry-sdk
     opentelemetry-instrumentation
     opentelemetry-proto
+    opentelemetry-distro
     tests/util
     instrumentation/*
     exporter/*

opentelemetry-distro/MANIFEST.in

@@ -0,0 +1,7 @@
+prune tests
+graft src
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude __pycache__/*
+include MANIFEST.in
+include README.rst

opentelemetry-distro/README.rst

@@ -0,0 +1,111 @@
+OpenTelemetry Distro
+====================
+
+|pypi|
+
+.. |pypi| image:: https://badge.fury.io/py/opentelemetry-distro.svg
+   :target: https://pypi.org/project/opentelemetry-distro/
+
+Installation
+------------
+
+::
+
+    pip install opentelemetry-distro
+
+
+This package provides a couple of commands that help automatically instruments a program:
+
+
+opentelemetry-bootstrap
+-----------------------
+
+::
+
+    opentelemetry-bootstrap --action=install|requirements
+
+This commands inspects the active Python site-packages and figures out which
+instrumentation packages the user might want to install. By default it prints out
+a list of the suggested instrumentation packages which can be added to a requirements.txt
+file. It also supports installing the suggested packages when run with :code:`--action=install`
+flag.
+
+
+opentelemetry-instrument
+------------------------
+
+::
+
+    opentelemetry-instrument python program.py
+
+The instrument command will try to automatically detect packages used by your python program
+and when possible, apply automatic tracing instrumentation on them. This means your program
+will get automatic distributed tracing for free without having to make any code changes
+at all. This will also configure a global tracer and tracing exporter without you having to
+make any code changes. By default, the instrument command will use the OTLP exporter but
+this can be overriden when needed.
+
+The command supports the following configuration options as CLI arguments and environment vars:
+
+
+* ``--exporter`` or ``OTEL_EXPORTER``
+
+Used to specify which trace exporter to use. Can be set to one or more
+of the well-known exporter names (see below).
+
+    - Defaults to `otlp`.
+    - Can be set to `none` to disable automatic tracer initialization. 
+
+You can pass multiple values to configure multiple exporters e.g, ``zipkin,prometheus`` 
+
+Well known trace exporter names:
+
+    - jaeger
+    - opencensus
+    - otlp
+    - otlp_span
+    - otlp_metric
+    - zipkin
+
+``otlp`` is an alias for ``otlp_span,otlp_metric``.
+
+* ``--service-name`` or ``OTEL_SERVICE_NAME``
+
+When present the value is passed on to the relevant exporter initializer as ``service_name`` argument.
+
+* ``--ids-generator`` or ``OTEL_IDS_GENERATOR``
+
+Used to specify which IDs Generator to use for the global Tracer Provider. By default, it
+will use the random IDs generator.
+
+The code in ``program.py`` needs to use one of the packages for which there is
+an OpenTelemetry integration. For a list of the available integrations please
+check `here <https://opentelemetry-python.readthedocs.io/en/stable/index.html#integrations>`_
+
+Examples
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    opentelemetry-instrument -e otlp flask run --port=3000
+
+The above command will pass ``-e otlp`` to the instrument command and ``--port=3000`` to ``flask run``.
+
+::
+
+    opentelemetry-instrument -e zipkin,otlp celery -A tasks worker --loglevel=info
+
+The above command will configure global trace provider, attach zipkin and otlp exporters to it and then
+start celery with the rest of the arguments. 
+
+::
+
+    opentelemetry-instrument --ids-generator random flask run --port=3000
+
+The above command will configure the global trace provider to use the Random IDs Generator, and then
+pass ``--port=3000`` to ``flask run``.
+
+References
+----------
+
+* `OpenTelemetry Project <https://opentelemetry.io/>`_

opentelemetry-distro/setup.cfg

@@ -0,0 +1,56 @@
+# 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-distro
+description = OpenTelemetry Python Distro
+long_description = file: README.rst
+long_description_content_type = text/x-rst
+author = OpenTelemetry Authors
+author_email = [email protected]
+url = https://github.com/open-telemetry/opentelemetry-python/tree/master/opentelemetry-distro
+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.5
+    Programming Language :: Python :: 3.6
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+
+[options]
+python_requires = >=3.5
+package_dir=
+    =src
+packages=find_namespace:
+zip_safe = False
+include_package_data = True
+install_requires =
+    opentelemetry-api == 0.17.dev0
+    opentelemetry-sdk == 0.17.dev0
+    opentelemetry-exporter-otlp == 0.17.dev0
+
+[options.packages.find]
+where = src
+
+[options.entry_points]
+opentelemetry_distro =
+    otel_distro = opentelemetry.distro:OpenTelemetryDistro
+
+[options.extras_require]
+test =

opentelemetry-distro/setup.py

@@ -0,0 +1,27 @@
+# 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.
+
+import os
+
+import setuptools
+
+BASE_DIR = os.path.dirname(__file__)
+VERSION_FILENAME = os.path.join(
+    BASE_DIR, "src", "opentelemetry", "distro", "version.py"
+)
+PACKAGE_INFO = {}
+with open(VERSION_FILENAME) as f:
+    exec(f.read(), PACKAGE_INFO)
+
+setuptools.setup(version=PACKAGE_INFO["__version__"],)

opentelemetry-distro/src/opentelemetry/distro/__init__.py

@@ -0,0 +1,27 @@
+# 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.
+#
+import os
+
+from opentelemetry.instrumentation.distro import BaseDistro
+
+
+class OpenTelemetryDistro(BaseDistro):
+    """
+    The OpenTelemetry provided Distro configures a default set of
+    configuration out of the box.
+    """
+
+    def _configure(self, **kwargs):
+        os.environ.setdefault("OTEL_EXPORTER", "otlp")

opentelemetry-distro/src/opentelemetry/distro/version.py

@@ -0,0 +1,15 @@
+# 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.
+
+__version__ = "0.17.dev0"

opentelemetry-distro/tests/test_distro.py

@@ -0,0 +1,27 @@
+# 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.
+# type: ignore
+
+from unittest import TestCase
+
+from pkg_resources import DistributionNotFound, require
+
+
+class TestDistribution(TestCase):
+    def test_proto(self):
+
+        try:
+            require(["opentelemetry-distro"])
+        except DistributionNotFound:
+            self.fail("opentelemetry-distro not installed")

opentelemetry-instrumentation/src/opentelemetry/instrumentation/auto_instrumentation/sitecustomize.py

@@ -22,8 +22,15 @@
 
 
 def _load_distros():
-    # will be implemented in a subsequent PR
-    pass
+    for entry_point in iter_entry_points("opentelemetry_distro"):
+        try:
+            entry_point.load()().configure()  # type: ignore
+            logger.debug("Distribution %s configured", entry_point.name)
+        except Exception as exc:  # pylint: disable=broad-except
+            logger.exception(
+                "Distribution %s configuration failed", entry_point.name
+            )
+            raise exc
 
 
 def _load_instrumentors():

opentelemetry-instrumentation/src/opentelemetry/instrumentation/distro.py

@@ -0,0 +1,47 @@
+# 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.
+# type: ignore
+
+"""
+OpenTelemetry Base Distribution (Distro)
+"""
+
+from abc import ABC, abstractmethod
+from logging import getLogger
+
+_LOG = getLogger(__name__)
+
+
+class BaseDistro(ABC):
+    """An ABC for distro"""
+
+    _instance = None
+
+    def __new__(cls, *args, **kwargs):
+
+        if cls._instance is None:
+            cls._instance = object.__new__(cls, *args, **kwargs)
+
+        return cls._instance
+
+    @abstractmethod
+    def _configure(self, **kwargs):
+        """Configure the distribution"""
+
+    def configure(self, **kwargs):
+        """Configure the distribution"""
+        self._configure(**kwargs)
+
+
+__all__ = ["BaseDistro"]

opentelemetry-sdk/src/opentelemetry/sdk/configuration/__init__.py

@@ -33,7 +33,7 @@
 EXPORTER_OTLP = "otlp"
 EXPORTER_OTLP_SPAN = "otlp_span"
 EXPORTER_OTLP_METRIC = "otlp_metric"
-_DEFAULT_EXPORTER = EXPORTER_OTLP
+_DEFAULT_EXPORTER = "none"
 
 RANDOM_IDS_GENERATOR = "random"
 _DEFAULT_IDS_GENERATOR = RANDOM_IDS_GENERATOR

scripts/build.sh

@@ -16,7 +16,7 @@ DISTDIR=dist
   mkdir -p $DISTDIR
   rm -rf $DISTDIR/*
 
- for d in opentelemetry-api/ opentelemetry-sdk/ opentelemetry-instrumentation/ opentelemetry-proto/ exporter/*/ instrumentation/*/ ; do
+ for d in opentelemetry-api/ opentelemetry-sdk/ opentelemetry-instrumentation/ opentelemetry-proto/ opentelemetry-distro/ exporter/*/ instrumentation/*/ ; do
    (
      echo "building $d"
      cd "$d"