Add opentelemetry-instrumentation (#1959)

Author: ocelotl

.github/pull_request_template.md

@@ -23,6 +23,7 @@ Please describe the tests that you ran to verify your changes. Provide instructi
 
 Answer the following question based on these examples of changes that would require a Contrib Repo Change:
 - [The OTel specification](https://github.com/open-telemetry/opentelemetry-specification) has changed which prompted this PR to update the method interfaces of `opentelemetry-api/` or `opentelemetry-sdk/`
+- The method interfaces of `opentelemetry-instrumentation/` have changed
 - The method interfaces of `test/util` have changed
 - Scripts in `scripts/` that were copied over to the Contrib repo have changed
 - Configuration files that were copied over to the Contrib repo have changed (when consistency between repositories is applicable) such as in

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#1946](https://github.com/open-telemetry/opentelemetry-python/pull/1946))
 
 ### Added
+- Moved `opentelemetry-instrumentation` to core repository.
+  ([#1959](https://github.com/open-telemetry/opentelemetry-python/pull/1959))
 - Dropped attributes/events/links count available exposed on ReadableSpans.
   ([#1893](https://github.com/open-telemetry/opentelemetry-python/pull/1893))
 - Added dropped count to otlp, jaeger and zipkin exporters.

docs-requirements.txt

@@ -8,8 +8,9 @@ sphinx-jekyll-builder
 # doesn't work for pkg_resources.
 ./opentelemetry-api
 ./opentelemetry-semantic-conventions
-./opentelemetry-python-contrib/opentelemetry-instrumentation
+./opentelemetry-instrumentation
 ./opentelemetry-sdk
+./opentelemetry-instrumentation
 
 # Required by instrumentation and exporter packages
 ddtrace>=0.34.0

docs/conf.py

@@ -23,6 +23,11 @@
 
 settings.configure()
 
+
+source_dirs = [
+    os.path.abspath("../opentelemetry-instrumentation/src/"),
+]
+
 exp = "../exporter"
 exp_dirs = [
     os.path.abspath("/".join(["../exporter", f, "src"]))
@@ -37,7 +42,7 @@
     if isdir(join(shim, f))
 ]
 
-sys.path[:0] = exp_dirs + shim_dirs
+sys.path[:0] = source_dirs + exp_dirs + shim_dirs
 
 # -- Project information -----------------------------------------------------
 

eachdist.ini

@@ -7,6 +7,7 @@ ignore=
 sortfirst=
     opentelemetry-api
     opentelemetry-sdk
+    opentelemetry-instrumentation
     opentelemetry-proto
     opentelemetry-distro
     tests/util

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,120 @@
+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:
+
+.. note::
+    You need to install a distro package to get auto instrumentation working. The ``opentelemetry-distro``
+    package contains the default distro and automatically configures some of the common options for users.
+    For more info about ``opentelemetry-distro`` check `here <https://opentelemetry-python.readthedocs.io/en/latest/examples/distro/README.html>`__
+    ::
+
+        pip install opentelemetry-distro[otlp]
+
+
+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 = [email protected]
+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.4.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)