Move opentelemetry-instrumentation from core

.github/workflows/test.yml

@@ -6,7 +6,7 @@ on:
     - 'release/*'
   pull_request:
 env:
-  CORE_REPO_SHA: 3e628b56f154d651816ba806b49940c6cc9a3556
+  CORE_REPO_SHA: 2ac247e8b666c6b5a735719ab78dc0cd94907d9b
 
 jobs:
   build:

CHANGELOG.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased](https://github.com/open-telemetry/opentelemetry-python-contrib/compare/v0.200...HEAD)
 
+### Added
+- Move `opentelemetry-instrumentation` from core repository
+  ([#465](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/465))
+
 ## [0.20b0](https://github.com/open-telemetry/opentelemetry-python-contrib/releases/tag/v0.20b0) - 2021-04-20
 
 ### Changed

docs-requirements.txt

@@ -7,7 +7,6 @@ sphinx-autodoc-typehints
 -e "git+https://github.com/open-telemetry/opentelemetry-python.git#egg=opentelemetry-api&subdirectory=opentelemetry-api"
 -e "git+https://github.com/open-telemetry/opentelemetry-python.git#egg=opentelemetry-semantic-conventions&subdirectory=opentelemetry-semantic-conventions"
 -e "git+https://github.com/open-telemetry/opentelemetry-python.git#egg=opentelemetry-sdk&subdirectory=opentelemetry-sdk"
--e "git+https://github.com/open-telemetry/opentelemetry-python.git#egg=opentelemetry-instrumentation&subdirectory=opentelemetry-instrumentation"
 
 # Required by opentelemetry-instrumentation
 fastapi~=0.58.1

docs/conf.py

@@ -24,6 +24,10 @@
 
 settings.configure()
 
+source_dirs = [
+    os.path.abspath("../opentelemetry-instrumentation/src/"),
+]
+
 exp = "../exporter"
 exp_dirs = [
     os.path.abspath("/".join(["../exporter", f, "src"]))
@@ -45,7 +49,7 @@
     if isdir(join(sdk_ext, f))
 ]
 
-sys.path[:0] = exp_dirs + instr_dirs + sdk_ext_dirs
+sys.path[:0] = source_dirs + exp_dirs + instr_dirs + sdk_ext_dirs
 
 # -- Project information -----------------------------------------------------
 

docs/instrumentation/base/instrumentation.rst

@@ -0,0 +1,15 @@
+OpenTelemetry Python Instrumentor
+=================================
+
+.. automodule:: opentelemetry.instrumentation
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+    :maxdepth: 1
+
+    instrumentor

docs/instrumentation/base/instrumentor.rst

@@ -0,0 +1,7 @@
+opentelemetry.instrumentation.instrumentor package
+==================================================
+
+.. automodule:: opentelemetry.instrumentation.instrumentor
+    :members:
+    :undoc-members:
+    :show-inheritance:

opentelemetry-instrumentation/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-instrumentation/README.rst

@@ -0,0 +1,112 @@
+OpenTelemetry Instrumentation
+=============================
+
+|pypi|
+
+.. |pypi| image:: https://badge.fury.io/py/opentelemetry-instrumentation.svg
+   :target: https://pypi.org/project/opentelemetry-instrumentation/
+
+Installation
+------------
+
+::
+
+    pip install opentelemetry-instrumentation
+
+
+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:
+
+
+* ``--trace-exporter`` or ``OTEL_TRACE_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_proto_grpc_span
+    - zipkin
+
+``otlp`` is an alias for ``otlp_proto_grpc_span``.
+
+* ``--id-generator`` or ``OTEL_PYTHON_ID_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>`_
+
+* ``OTEL_PYTHON_DISABLED_INSTRUMENTATIONS``
+
+If set by the user, opentelemetry-instrument will read this environment variable to disable specific instrumentations.
+e.g OTEL_PYTHON_DISABLED_INSTRUMENTATIONS = "requests,django"
+
+
+Examples
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    opentelemetry-instrument --trace-exporter otlp flask run --port=3000
+
+The above command will pass ``--trace-exporter otlp`` to the instrument command and ``--port=3000`` to ``flask run``.
+
+::
+
+    opentelemetry-instrument --trace-exporter 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-instrumentation/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-instrumentation
+description = Instrumentation Tools & Auto Instrumentation for OpenTelemetry Python
+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-contrib/tree/main/opentelemetry-instrumentation
+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.6
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+    Programming Language :: Python :: 3.9
+
+[options]
+python_requires = >=3.6
+package_dir=
+    =src
+packages=find_namespace:
+zip_safe = False
+include_package_data = True
+install_requires =
+    opentelemetry-api == 1.2.0.dev0
+    wrapt >= 1.0.0, < 2.0.0
+
+[options.packages.find]
+where = src
+
+[options.entry_points]
+console_scripts =
+    opentelemetry-instrument = opentelemetry.instrumentation.auto_instrumentation:run
+    opentelemetry-bootstrap = opentelemetry.instrumentation.bootstrap:run
+
+[options.extras_require]
+test =

opentelemetry-instrumentation/setup.py

@@ -0,0 +1,29 @@
+# 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", "instrumentation", "version.py"
+)
+PACKAGE_INFO = {}
+with open(VERSION_FILENAME) as f:
+    exec(f.read(), PACKAGE_INFO)
+
+setuptools.setup(
+    version=PACKAGE_INFO["__version__"],
+)

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

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+
+# 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 argparse
+from logging import getLogger
+from os import environ, execl, getcwd
+from os.path import abspath, dirname, pathsep
+from shutil import which
+
+from opentelemetry.environment_variables import (
+    OTEL_PYTHON_ID_GENERATOR,
+    OTEL_TRACES_EXPORTER,
+)
+
+logger = getLogger(__file__)
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="""
+        opentelemetry-instrument automatically instruments a Python
+        program and it's dependencies and then runs the program.
+        """
+    )
+
+    parser.add_argument(
+        "--trace-exporter",
+        required=False,
+        help="""
+        Uses the specified exporter to export spans.
+        Accepts multiple exporters as comma separated values.
+
+        Examples:
+
+            --trace-exporter=jaeger
+        """,
+    )
+
+    parser.add_argument(
+        "--id-generator",
+        required=False,
+        help="""
+        The IDs Generator to be used with the Tracer Provider.
+
+        Examples:
+
+            --id-generator=random
+        """,
+    )
+
+    parser.add_argument("command", help="Your Python application.")
+    parser.add_argument(
+        "command_args",
+        help="Arguments for your application.",
+        nargs=argparse.REMAINDER,
+    )
+    return parser.parse_args()
+
+
+def load_config_from_cli_args(args):
+    if args.trace_exporter:
+        environ[OTEL_TRACES_EXPORTER] = args.trace_exporter
+    if args.id_generator:
+        environ[OTEL_PYTHON_ID_GENERATOR] = args.id_generator
+
+
+def run() -> None:
+    args = parse_args()
+    load_config_from_cli_args(args)
+
+    python_path = environ.get("PYTHONPATH")
+
+    if not python_path:
+        python_path = []
+
+    else:
+        python_path = python_path.split(pathsep)
+
+    cwd_path = getcwd()
+
+    # This is being added to support applications that are being run from their
+    # own executable, like Django.
+    # FIXME investigate if there is another way to achieve this
+    if cwd_path not in python_path:
+        python_path.insert(0, cwd_path)
+
+    filedir_path = dirname(abspath(__file__))
+
+    python_path = [path for path in python_path if path != filedir_path]
+
+    python_path.insert(0, filedir_path)
+
+    environ["PYTHONPATH"] = pathsep.join(python_path)
+
+    executable = which(args.command)
+    execl(executable, executable, *args.command_args)