Merge branch 'master' into feature/trace-get-current-span

README.md

@@ -1,6 +1,42 @@
-# OpenTelemetry Python
-[![Gitter chat](https://img.shields.io/gitter/room/opentelemetry/opentelemetry-python)](https://gitter.im/open-telemetry/opentelemetry-python)
-[![Build status](https://travis-ci.org/open-telemetry/opentelemetry-python.svg?branch=master)](https://travis-ci.org/open-telemetry/opentelemetry-python)
+---
+<p align="center">
+  <strong>
+    <a href="https://opentelemetry-python.readthedocs.io/en/stable/getting-started.html">Getting Started<a/>
+    &nbsp;&nbsp;&bull;&nbsp;&nbsp;
+    <a href="https://opentelemetry-python.readthedocs.io/">API Documentation<a/>
+    &nbsp;&nbsp;&bull;&nbsp;&nbsp;
+    <a href="https://gitter.im/open-telemetry/opentelemetry-python">Getting In Touch (Gitter)<a/>
+  </strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/open-telemetry/opentelemetry-python/releases">
+    <img alt="GitHub release (latest by date including pre-releases)" src="https://img.shields.io/github/v/release/open-telemetry/opentelemetry-python?include_prereleases&style=for-the-badge">
+  </a>
+  <a href="https://codecov.io/gh/open-telemetry/opentelemetry-python/branch/master/">
+    <img alt="Codecov Status" src="https://img.shields.io/codecov/c/github/open-telemetry/opentelemetry-python?style=for-the-badge">
+  </a>
+  <a href="https://github.com/open-telemetry/opentelemetry-python/blob/master/LICENSE">
+    <img alt="license" src="https://img.shields.io/badge/license-Apache_2.0-green.svg?style=for-the-badge">
+  </a>
+  <br/>
+  <a href="https://travis-ci.org/open-telemetry/opentelemetry-python">
+    <img alt="Build Status" src="https://travis-ci.org/open-telemetry/opentelemetry-python.svg?branch=master">
+  </a>
+  <img alt="Beta" src="https://img.shields.io/badge/status-beta-informational?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAAXNSR0IArs4c6QAAAIRlWElmTU0AKgAAAAgABQESAAMAAAABAAEAAAEaAAUAAAABAAAASgEbAAUAAAABAAAAUgEoAAMAAAABAAIAAIdpAAQAAAABAAAAWgAAAAAAAACQAAAAAQAAAJAAAAABAAOgAQADAAAAAQABAACgAgAEAAAAAQAAABigAwAEAAAAAQAAABgAAAAA8A2UOAAAAAlwSFlzAAAWJQAAFiUBSVIk8AAAAVlpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IlhNUCBDb3JlIDUuNC4wIj4KICAgPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICAgICAgPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIKICAgICAgICAgICAgeG1sbnM6dGlmZj0iaHR0cDovL25zLmFkb2JlLmNvbS90aWZmLzEuMC8iPgogICAgICAgICA8dGlmZjpPcmllbnRhdGlvbj4xPC90aWZmOk9yaWVudGF0aW9uPgogICAgICA8L3JkZjpEZXNjcmlwdGlvbj4KICAgPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KTMInWQAABK5JREFUSA2dVm1sFEUYfmd2b/f2Pkqghn5eEQWKrRgjpkYgpoRCLC0oxV5apAiGUDEpJvwxEQ2raWPU+Kf8INU/RtEedwTCR9tYPloxGNJYTTQUwYqJ1aNpaLH3sXu3t7vjvFevpSqt7eSyM+/czvM8877PzB3APBoLgoDLsNePF56LBwqa07EKlDGg84CcWsI4CEbhNnDpAd951lXE2NkiNknCCTLv4HtzZuvPm1C/IKv4oDNXqNDHragety2XVzjECZsJARuBMyRzJrh1O0gQwLXuxofxsPSj4hG8fMLQo7bl9JJD8XZfC1E5yWFOMtd07dvX5kDwg6+2++Chq8txHGtfPoAp0gOFmhYoNFkHjn2TNUmrwRdna7W1QSkU8hvbGk4uThLrapaiLA2E6QY4u/lS9ItHfvJkxYsTMVtnAJLipYIWtVrcdX+8+b8IVnPl/R81prbuPZ1jpYw+0aEUGSkdFsgyBIaFTXCm6nyaxMtJ4n+TeDhJzGqZtQZcuYDgqDwDbqb0JF9oRpIG1Oea3bC1Y6N3x/WV8Zh83emhCs++hlaghDw+8w5UlYKq2lU7Pl8IkvS9KDqXmKmEwdMppVPKwGSEilmyAwJhRwWcq7wYC6z4wZ1rrEoMWxecdOjZWXeAQClBcYDN3NwVwD9pGwqUSyQgclcmxpNJqCuwLmDh3WtvPqXdlt+6Oz70HPGDNSNBee/EOen+rGbEFqDENBPDbtdCp0ukPANmzO0QQJYUpyS5IJJI3Hqt4maS+EB3199ozm8EDU/6fVNU2dQpdx3ZnKzeFXyaUTiasEV/gZMzJMjr3Z+WvAdQ+hs/zw9savimxUntDSaBdZ2f+Idbm1rlNY8esFffBit9HtK5/MejsrJVxikOXlb1Ukir2X+Rbdkd1KG2Ixfn2Ql4JRmELnYK9mEM8G36fAA3xEQ89fxXihC8q+sAKi9jhHxNqagY2hiaYgRCm0f0QP7H4Fp11LSXiuBY2aYFlh0DeDIVVFUJQn5rCnpiNI2gvLxHnASn9DIVHJJlm5rXvQAGEo4zvKq2w5G1NxENN7jrft1oxMdekETjxdH2Z3x+VTVYsPb+O0C/9/auN6v2hNZw5b2UOmSbG5/rkC3LBA+1PdxFxORjxpQ81GcxKc+ybVjEBvUJvaGJ7p7n5A5KSwe4AzkasA+crmzFtowoIVTiLjANm8GDsrWW35ScI3JY8Urv83tnkF8JR0yLvEt2hO/0qNyy3Jb3YKeHeHeLeOuVLRpNF+pkf85OW7/zJxWdXsbsKBUk2TC0BCPwMq5Q/CPvaJFkNS/1l1qUPe+uH3oD59erYGI/Y4sce6KaXYElAIOLt+0O3t2+/xJDF1XvOlWGC1W1B8VMszbGfOvT5qaRRAIFK3BCO164nZ0uYLH2YjNN8thXS2v2BK9gTfD7jHVxzHr4roOlEvYYz9QIz+Vl/sLDXInsctFsXjqIRnO2ZO387lxmIboLDZCJ59KLFliNIgh9ipt6tLg9SihpRPDO1ia5byw7de1aCQmF5geOQtK509rzfdwxaKOIq+73AvwCC5/5fcV4vo3+3LpMdtWHh0ywsJC/ZGoCb8/9D8F/ifgLLl8S8QWfU8cAAAAASUVORK5CYII=">
+</p>
+
+<p align="center">
+  <strong>
+    <a href="CONTRIBUTING.md">Contributing<a/>
+    &nbsp;&nbsp;&bull;&nbsp;&nbsp;
+    <a href="https://opentelemetry-python.readthedocs.io/en/stable/#examples">Examples<a/>
+  </strong>
+</p>
+
+---
+
+## About this project
 
 The Python [OpenTelemetry](https://opentelemetry.io/) client.
 

docs/examples/opentelemetry-example-app/src/opentelemetry_example_app/flask_example.py

@@ -34,15 +34,15 @@
 trace.set_tracer_provider(TracerProvider())
 
 opentelemetry.ext.requests.RequestsInstrumentor().instrument()
-FlaskInstrumentor().instrument()
 
 trace.get_tracer_provider().add_span_processor(
     SimpleExportSpanProcessor(ConsoleSpanExporter())
 )
 
-
 app = flask.Flask(__name__)
 
+FlaskInstrumentor().instrument_app(app)
+
 
 @app.route("/")
 def hello():

docs/getting-started.rst

@@ -184,9 +184,6 @@ And let's write a small Flask application that sends an HTTP request, activating
 .. code-block:: python
 
     # flask_example.py
-    from opentelemetry.ext.flask import FlaskInstrumentor
-    FlaskInstrumentor().instrument()  # This needs to be executed before importing Flask
-
     import flask
     import requests
 
@@ -195,14 +192,16 @@ And let's write a small Flask application that sends an HTTP request, activating
     from opentelemetry.sdk.trace import TracerProvider
     from opentelemetry.sdk.trace.export import ConsoleSpanExporter
     from opentelemetry.sdk.trace.export import SimpleExportSpanProcessor
+    from opentelemetry.ext.flask import FlaskInstrumentor
 
     trace.set_tracer_provider(TracerProvider())
     trace.get_tracer_provider().add_span_processor(
         SimpleExportSpanProcessor(ConsoleSpanExporter())
     )
 
     app = flask.Flask(__name__)
-    opentelemetry.ext.requests.RequestsInstrumentor().instrument()
+    FlaskInstrumentor().instrument_app(app)
+    opentelemetry.ext.http_requests.RequestsInstrumentor().instrument()
 
     @app.route("/")
     def hello():

ext/opentelemetry-ext-flask/src/opentelemetry/ext/flask/__init__.py

@@ -29,12 +29,13 @@
 
 .. code-block:: python
 
-    from opentelemetry.ext.flask import FlaskInstrumentor
-    FlaskInstrumentor().instrument()  # This needs to be executed before importing Flask
     from flask import Flask
+    from opentelemetry.ext.flask import FlaskInstrumentor
 
     app = Flask(__name__)
 
+    FlaskInstrumentor().instrument_app(app)
+
     @app.route("/")
     def hello():
         return "Hello!"
@@ -46,7 +47,7 @@ def hello():
 ---
 """
 
-import logging
+from logging import getLogger
 
 import flask
 
@@ -60,110 +61,112 @@ def hello():
     time_ns,
 )
 
-logger = logging.getLogger(__name__)
+_logger = getLogger(__name__)
 
 _ENVIRON_STARTTIME_KEY = "opentelemetry-flask.starttime_key"
 _ENVIRON_SPAN_KEY = "opentelemetry-flask.span_key"
 _ENVIRON_ACTIVATION_KEY = "opentelemetry-flask.activation_key"
 _ENVIRON_TOKEN = "opentelemetry-flask.token"
 
 
+def _rewrapped_app(wsgi_app):
+    def _wrapped_app(environ, start_response):
+        # We want to measure the time for route matching, etc.
+        # In theory, we could start the span here and use
+        # update_name later but that API is "highly discouraged" so
+        # we better avoid it.
+        environ[_ENVIRON_STARTTIME_KEY] = time_ns()
+
+        def _start_response(status, response_headers, *args, **kwargs):
+
+            if not _disable_trace(flask.request.url):
+
+                span = flask.request.environ.get(_ENVIRON_SPAN_KEY)
+
+                if span:
+                    otel_wsgi.add_response_attributes(
+                        span, status, response_headers
+                    )
+                else:
+                    _logger.warning(
+                        "Flask environ's OpenTelemetry span "
+                        "missing at _start_response(%s)",
+                        status,
+                    )
+
+            return start_response(status, response_headers, *args, **kwargs)
+
+        return wsgi_app(environ, _start_response)
+
+    return _wrapped_app
+
+
+def _before_request():
+    if _disable_trace(flask.request.url):
+        return
+
+    environ = flask.request.environ
+    span_name = flask.request.endpoint or otel_wsgi.get_default_span_name(
+        environ
+    )
+    token = context.attach(
+        propagators.extract(otel_wsgi.get_header_from_environ, environ)
+    )
+
+    tracer = trace.get_tracer(__name__, __version__)
+
+    attributes = otel_wsgi.collect_request_attributes(environ)
+    if flask.request.url_rule:
+        # For 404 that result from no route found, etc, we
+        # don't have a url_rule.
+        attributes["http.route"] = flask.request.url_rule.rule
+    span = tracer.start_span(
+        span_name,
+        kind=trace.SpanKind.SERVER,
+        attributes=attributes,
+        start_time=environ.get(_ENVIRON_STARTTIME_KEY),
+    )
+    activation = tracer.use_span(span, end_on_exit=True)
+    activation.__enter__()
+    environ[_ENVIRON_ACTIVATION_KEY] = activation
+    environ[_ENVIRON_SPAN_KEY] = span
+    environ[_ENVIRON_TOKEN] = token
+
+
+def _teardown_request(exc):
+    activation = flask.request.environ.get(_ENVIRON_ACTIVATION_KEY)
+    if not activation:
+        _logger.warning(
+            "Flask environ's OpenTelemetry activation missing"
+            "at _teardown_flask_request(%s)",
+            exc,
+        )
+        return
+
+    if exc is None:
+        activation.__exit__(None, None, None)
+    else:
+        activation.__exit__(
+            type(exc), exc, getattr(exc, "__traceback__", None)
+        )
+    context.detach(flask.request.environ.get(_ENVIRON_TOKEN))
+
+
 class _InstrumentedFlask(flask.Flask):
     def __init__(self, *args, **kwargs):
-
         super().__init__(*args, **kwargs)
 
-        # Single use variable here to avoid recursion issues.
-        wsgi = self.wsgi_app
-
-        def wrapped_app(environ, start_response):
-            # We want to measure the time for route matching, etc.
-            # In theory, we could start the span here and use
-            # update_name later but that API is "highly discouraged" so
-            # we better avoid it.
-            environ[_ENVIRON_STARTTIME_KEY] = time_ns()
-
-            def _start_response(status, response_headers, *args, **kwargs):
-                if not _disable_trace(flask.request.url):
-                    span = flask.request.environ.get(_ENVIRON_SPAN_KEY)
-                    if span:
-                        otel_wsgi.add_response_attributes(
-                            span, status, response_headers
-                        )
-                    else:
-                        logger.warning(
-                            "Flask environ's OpenTelemetry span "
-                            "missing at _start_response(%s)",
-                            status,
-                        )
-
-                return start_response(
-                    status, response_headers, *args, **kwargs
-                )
-
-            return wsgi(environ, _start_response)
-
-        self.wsgi_app = wrapped_app
-
-        @self.before_request
-        def _before_flask_request():
-            # Do not trace if the url is excluded
-            if _disable_trace(flask.request.url):
-                return
-            environ = flask.request.environ
-            span_name = (
-                flask.request.endpoint
-                or otel_wsgi.get_default_span_name(environ)
-            )
-            token = context.attach(
-                propagators.extract(otel_wsgi.get_header_from_environ, environ)
-            )
+        self._original_wsgi_ = self.wsgi_app
+        self.wsgi_app = _rewrapped_app(self.wsgi_app)
 
-            tracer = trace.get_tracer(__name__, __version__)
-
-            attributes = otel_wsgi.collect_request_attributes(environ)
-            if flask.request.url_rule:
-                # For 404 that result from no route found, etc, we
-                # don't have a url_rule.
-                attributes["http.route"] = flask.request.url_rule.rule
-            span = tracer.start_span(
-                span_name,
-                kind=trace.SpanKind.SERVER,
-                attributes=attributes,
-                start_time=environ.get(_ENVIRON_STARTTIME_KEY),
-            )
-            activation = tracer.use_span(span, end_on_exit=True)
-            activation.__enter__()
-            environ[_ENVIRON_ACTIVATION_KEY] = activation
-            environ[_ENVIRON_SPAN_KEY] = span
-            environ[_ENVIRON_TOKEN] = token
-
-        @self.teardown_request
-        def _teardown_flask_request(exc):
-            # Not traced if the url is excluded
-            if _disable_trace(flask.request.url):
-                return
-            activation = flask.request.environ.get(_ENVIRON_ACTIVATION_KEY)
-            if not activation:
-                logger.warning(
-                    "Flask environ's OpenTelemetry activation missing"
-                    "at _teardown_flask_request(%s)",
-                    exc,
-                )
-                return
-
-            if exc is None:
-                activation.__exit__(None, None, None)
-            else:
-                activation.__exit__(
-                    type(exc), exc, getattr(exc, "__traceback__", None)
-                )
-            context.detach(flask.request.environ.get(_ENVIRON_TOKEN))
+        self.before_request(_before_request)
+        self.teardown_request(_teardown_request)
 
 
 def _disable_trace(url):
     excluded_hosts = configuration.Configuration().FLASK_EXCLUDED_HOSTS
     excluded_paths = configuration.Configuration().FLASK_EXCLUDED_PATHS
+
     if excluded_hosts:
         excluded_hosts = str.split(excluded_hosts, ",")
         if disable_tracing_hostname(url, excluded_hosts):
@@ -176,18 +179,50 @@ def _disable_trace(url):
 
 
 class FlaskInstrumentor(BaseInstrumentor):
-    """A instrumentor for flask.Flask
+    # pylint: disable=protected-access,attribute-defined-outside-init
+    """An instrumentor for flask.Flask
 
     See `BaseInstrumentor`
     """
 
-    def __init__(self):
-        super().__init__()
-        self._original_flask = None
-
     def _instrument(self, **kwargs):
         self._original_flask = flask.Flask
         flask.Flask = _InstrumentedFlask
 
+    def instrument_app(self, app):  # pylint: disable=no-self-use
+        if not hasattr(app, "_is_instrumented"):
+            app._is_instrumented = False
+
+        if not app._is_instrumented:
+            app._original_wsgi_app = app.wsgi_app
+            app.wsgi_app = _rewrapped_app(app.wsgi_app)
+
+            app.before_request(_before_request)
+            app.teardown_request(_teardown_request)
+            app._is_instrumented = True
+        else:
+            _logger.warning(
+                "Attempting to instrument Flask app while already instrumented"
+            )
+
     def _uninstrument(self, **kwargs):
         flask.Flask = self._original_flask
+
+    def uninstrument_app(self, app):  # pylint: disable=no-self-use
+        if not hasattr(app, "_is_instrumented"):
+            app._is_instrumented = False
+
+        if app._is_instrumented:
+            app.wsgi_app = app._original_wsgi_app
+
+            # FIXME add support for other Flask blueprints that are not None
+            app.before_request_funcs[None].remove(_before_request)
+            app.teardown_request_funcs[None].remove(_teardown_request)
+            del app._original_wsgi_app
+
+            app._is_instrumented = False
+        else:
+            _logger.warning(
+                "Attempting to uninstrument Flask "
+                "app while already uninstrumented"
+            )