From 7bec76a22032e498911d06b9e3dab4e33528d995 Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Wed, 15 Jul 2020 06:49:12 +0000 Subject: [PATCH] fastapi instrumentation (#890) Co-authored-by: Leighton Chen --- docs-requirements.txt | 1 + docs/ext/fastapi/fastapi.rst | 9 ++ .../CHANGELOG.md | 5 + .../README.rst | 43 ++++++++ .../setup.cfg | 55 +++++++++ .../setup.py | 31 ++++++ .../instrumentation/fastapi/__init__.py | 82 ++++++++++++++ .../instrumentation/fastapi/version.py | 15 +++ .../tests/__init__.py | 0 .../tests/test_fastapi_instrumentation.py | 104 ++++++++++++++++++ .../setup.cfg | 2 +- .../instrumentation/starlette/__init__.py | 2 +- tox.ini | 16 ++- 13 files changed, 358 insertions(+), 7 deletions(-) create mode 100644 docs/ext/fastapi/fastapi.rst create mode 100644 ext/opentelemetry-instrumentation-fastapi/CHANGELOG.md create mode 100644 ext/opentelemetry-instrumentation-fastapi/README.rst create mode 100644 ext/opentelemetry-instrumentation-fastapi/setup.cfg create mode 100644 ext/opentelemetry-instrumentation-fastapi/setup.py create mode 100644 ext/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/__init__.py create mode 100644 ext/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/version.py create mode 100644 ext/opentelemetry-instrumentation-fastapi/tests/__init__.py create mode 100644 ext/opentelemetry-instrumentation-fastapi/tests/test_fastapi_instrumentation.py diff --git a/docs-requirements.txt b/docs-requirements.txt index 230c76149c..169bbb7f0b 100644 --- a/docs-requirements.txt +++ b/docs-requirements.txt @@ -29,3 +29,4 @@ google-cloud-trace >=0.23.0 google-cloud-monitoring>=0.36.0 botocore~=1.0 starlette~=0.13 +fastapi~=0.58.1 \ No newline at end of file diff --git a/docs/ext/fastapi/fastapi.rst b/docs/ext/fastapi/fastapi.rst new file mode 100644 index 0000000000..9295261584 --- /dev/null +++ b/docs/ext/fastapi/fastapi.rst @@ -0,0 +1,9 @@ +.. include:: ../../../ext/opentelemetry-instrumentation-fastapi/README.rst + +API +--- + +.. automodule:: opentelemetry.instrumentation.fastapi + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/ext/opentelemetry-instrumentation-fastapi/CHANGELOG.md b/ext/opentelemetry-instrumentation-fastapi/CHANGELOG.md new file mode 100644 index 0000000000..684dece0c6 --- /dev/null +++ b/ext/opentelemetry-instrumentation-fastapi/CHANGELOG.md @@ -0,0 +1,5 @@ +# Changelog + +## Unreleased + +- Initial release ([#890](https://github.com/open-telemetry/opentelemetry-python/pull/890)) \ No newline at end of file diff --git a/ext/opentelemetry-instrumentation-fastapi/README.rst b/ext/opentelemetry-instrumentation-fastapi/README.rst new file mode 100644 index 0000000000..4cc612da76 --- /dev/null +++ b/ext/opentelemetry-instrumentation-fastapi/README.rst @@ -0,0 +1,43 @@ +OpenTelemetry FastAPI Instrumentation +======================================= + +|pypi| + +.. |pypi| image:: https://badge.fury.io/py/opentelemetry-instrumentation-fastapi.svg + :target: https://pypi.org/project/opentelemetry-instrumentation-fastapi/ + + +This library provides automatic and manual instrumentation of FastAPI web frameworks, +instrumenting http requests served by applications utilizing the framework. + +auto-instrumentation using the opentelemetry-instrumentation package is also supported. + +Installation +------------ + +:: + + pip install opentelemetry-instrumentation-fastapi + + +Usage +----- + +.. code-block:: python + + import fastapi + from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor + + app = fastapi.FastAPI() + + @app.get("/foobar") + async def foobar(): + return {"message": "hello world"} + + FastAPIInstrumentor.instrument_app(app) + + +References +---------- + +* `OpenTelemetry Project `_ \ No newline at end of file diff --git a/ext/opentelemetry-instrumentation-fastapi/setup.cfg b/ext/opentelemetry-instrumentation-fastapi/setup.cfg new file mode 100644 index 0000000000..5e7c2fafa6 --- /dev/null +++ b/ext/opentelemetry-instrumentation-fastapi/setup.cfg @@ -0,0 +1,55 @@ +# 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-fastapi +description = OpenTelemetry FastAPI Instrumentation +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/ext/opentelemetry-instrumentation-fastapi +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 + +[options] +python_requires = >=3.6 +package_dir= + =src +packages=find_namespace: +install_requires = + opentelemetry-api == 0.11.dev0 + opentelemetry-ext-asgi == 0.11.dev0 + +[options.entry_points] +opentelemetry_instrumentor = + fastapi = opentelemetry.instrumentation.fastapi:FastAPIInstrumentor + +[options.extras_require] +test = + opentelemetry-test == 0.11.dev0 + fastapi ~= 0.58.1 + requests ~= 2.23.0 # needed for testclient + +[options.packages.find] +where = src diff --git a/ext/opentelemetry-instrumentation-fastapi/setup.py b/ext/opentelemetry-instrumentation-fastapi/setup.py new file mode 100644 index 0000000000..13c7c5a99c --- /dev/null +++ b/ext/opentelemetry-instrumentation-fastapi/setup.py @@ -0,0 +1,31 @@ +# 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", + "fastapi", + "version.py", +) +PACKAGE_INFO = {} +with open(VERSION_FILENAME) as f: + exec(f.read(), PACKAGE_INFO) + +setuptools.setup(version=PACKAGE_INFO["__version__"]) diff --git a/ext/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/__init__.py b/ext/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/__init__.py new file mode 100644 index 0000000000..65d608393d --- /dev/null +++ b/ext/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/__init__.py @@ -0,0 +1,82 @@ +# 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 typing import Optional + +import fastapi +from starlette.routing import Match + +from opentelemetry.ext.asgi import OpenTelemetryMiddleware +from opentelemetry.instrumentation.fastapi.version import __version__ # noqa +from opentelemetry.instrumentation.instrumentor import BaseInstrumentor + + +class FastAPIInstrumentor(BaseInstrumentor): + """An instrumentor for FastAPI + + See `BaseInstrumentor` + """ + + _original_fastapi = None + + @staticmethod + def instrument_app(app: fastapi.FastAPI): + """Instrument an uninstrumented FastAPI application. + """ + if not getattr(app, "is_instrumented_by_opentelemetry", False): + app.add_middleware( + OpenTelemetryMiddleware, + span_details_callback=_get_route_details, + ) + app.is_instrumented_by_opentelemetry = True + + def _instrument(self, **kwargs): + self._original_fastapi = fastapi.FastAPI + fastapi.FastAPI = _InstrumentedFastAPI + + def _uninstrument(self, **kwargs): + fastapi.FastAPI = self._original_fastapi + + +class _InstrumentedFastAPI(fastapi.FastAPI): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + self.add_middleware( + OpenTelemetryMiddleware, span_details_callback=_get_route_details + ) + + +def _get_route_details(scope): + """Callback to retrieve the fastapi route being served. + + TODO: there is currently no way to retrieve http.route from + a starlette application from scope. + + See: https://github.com/encode/starlette/pull/804 + """ + app = scope["app"] + route = None + for starlette_route in app.routes: + match, _ = starlette_route.matches(scope) + if match == Match.FULL: + route = starlette_route.path + break + if match == Match.PARTIAL: + route = starlette_route.path + # method only exists for http, if websocket + # leave it blank. + span_name = route or scope.get("method", "") + attributes = {} + if route: + attributes["http.route"] = route + return span_name, attributes diff --git a/ext/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/version.py b/ext/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/version.py new file mode 100644 index 0000000000..858e73960f --- /dev/null +++ b/ext/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/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.11.dev0" diff --git a/ext/opentelemetry-instrumentation-fastapi/tests/__init__.py b/ext/opentelemetry-instrumentation-fastapi/tests/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/ext/opentelemetry-instrumentation-fastapi/tests/test_fastapi_instrumentation.py b/ext/opentelemetry-instrumentation-fastapi/tests/test_fastapi_instrumentation.py new file mode 100644 index 0000000000..47617d4e95 --- /dev/null +++ b/ext/opentelemetry-instrumentation-fastapi/tests/test_fastapi_instrumentation.py @@ -0,0 +1,104 @@ +# 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 unittest + +import fastapi +from fastapi.testclient import TestClient + +import opentelemetry.instrumentation.fastapi as otel_fastapi +from opentelemetry.test.test_base import TestBase + + +class TestFastAPIManualInstrumentation(TestBase): + def _create_app(self): + app = self._create_fastapi_app() + self._instrumentor.instrument_app(app) + return app + + def setUp(self): + super().setUp() + self._instrumentor = otel_fastapi.FastAPIInstrumentor() + self._app = self._create_app() + self._client = TestClient(self._app) + + def test_basic_fastapi_call(self): + self._client.get("/foobar") + spans = self.memory_exporter.get_finished_spans() + self.assertEqual(len(spans), 3) + for span in spans: + self.assertIn("/foobar", span.name) + + def test_fastapi_route_attribute_added(self): + """Ensure that fastapi routes are used as the span name.""" + self._client.get("/user/123") + spans = self.memory_exporter.get_finished_spans() + self.assertEqual(len(spans), 3) + for span in spans: + self.assertIn("/user/{username}", span.name) + self.assertEqual( + spans[-1].attributes["http.route"], "/user/{username}" + ) + # ensure that at least one attribute that is populated by + # the asgi instrumentation is successfully feeding though. + self.assertEqual(spans[-1].attributes["http.flavor"], "1.1") + + @staticmethod + def _create_fastapi_app(): + app = fastapi.FastAPI() + + @app.get("/foobar") + async def _(): + return {"message": "hello world"} + + @app.get("/user/{username}") + async def _(username: str): + return {"message": username} + + return app + + +class TestAutoInstrumentation(TestFastAPIManualInstrumentation): + """Test the auto-instrumented variant + + Extending the manual instrumentation as most test cases apply + to both. + """ + + def _create_app(self): + # instrumentation is handled by the instrument call + self._instrumentor.instrument() + return self._create_fastapi_app() + + def tearDown(self): + self._instrumentor.uninstrument() + super().tearDown() + + +class TestAutoInstrumentationLogic(unittest.TestCase): + def test_instrumentation(self): + """Verify that instrumentation methods are instrumenting and + removing as expected. + """ + instrumentor = otel_fastapi.FastAPIInstrumentor() + original = fastapi.FastAPI + instrumentor.instrument() + try: + instrumented = fastapi.FastAPI + self.assertIsNot(original, instrumented) + finally: + instrumentor.uninstrument() + + should_be_original = fastapi.FastAPI + self.assertIs(original, should_be_original) diff --git a/ext/opentelemetry-instrumentation-starlette/setup.cfg b/ext/opentelemetry-instrumentation-starlette/setup.cfg index cea0cc1188..4c777a18c5 100644 --- a/ext/opentelemetry-instrumentation-starlette/setup.cfg +++ b/ext/opentelemetry-instrumentation-starlette/setup.cfg @@ -19,7 +19,7 @@ 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/ext/opentelemetry-instrumentation-starlette +url = https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-instrumentation-starlette platforms = any license = Apache-2.0 classifiers = diff --git a/ext/opentelemetry-instrumentation-starlette/src/opentelemetry/instrumentation/starlette/__init__.py b/ext/opentelemetry-instrumentation-starlette/src/opentelemetry/instrumentation/starlette/__init__.py index 197a38d759..b8763bba05 100644 --- a/ext/opentelemetry-instrumentation-starlette/src/opentelemetry/instrumentation/starlette/__init__.py +++ b/ext/opentelemetry-instrumentation-starlette/src/opentelemetry/instrumentation/starlette/__init__.py @@ -31,7 +31,7 @@ class StarletteInstrumentor(BaseInstrumentor): @staticmethod def instrument_app(app: applications.Starlette): - """Instrument a previously instrumented Starlette application. + """Instrument an uninstrumented Starlette application. """ if not getattr(app, "is_instrumented_by_opentelemetry", False): app.add_middleware( diff --git a/tox.ini b/tox.ini index ed4122a3ce..4b9ed90479 100644 --- a/tox.ini +++ b/tox.ini @@ -52,6 +52,11 @@ envlist = py3{4,5,6,7,8}-test-instrumentation-elasticsearch{2,5,6,7} pypy3-test-instrumentation-elasticsearch{2,5,6,7} + ; opentelemetry-instrumentation-fastapi + ; fastapi only supports 3.6 and above. + py3{6,7,8}-test-instrumentation-fastapi + pypy3-test-instrumentation-fastapi + ; opentelemetry-ext-flask py3{4,5,6,7,8}-test-instrumentation-flask pypy3-test-instrumentation-flask @@ -187,8 +192,7 @@ deps = elasticsearch7: elasticsearch-dsl>=7.0,<8.0 elasticsearch7: elasticsearch>=7.0,<8.0 -setenv = - mypy: MYPYPATH={toxinidir}/opentelemetry-api/src/ +setenv = mypy: MYPYPATH={toxinidir}/opentelemetry-api/src/ changedir = test-core-api: opentelemetry-api/tests @@ -215,6 +219,7 @@ changedir = test-instrumentation-wsgi: ext/opentelemetry-ext-wsgi/tests test-instrumentation-boto: ext/opentelemetry-ext-boto/tests test-instrumentation-botocore: ext/opentelemetry-ext-botocore/tests + test-instrumentation-fastapi: ext/opentelemetry-instrumentation-fastapi/tests test-instrumentation-flask: ext/opentelemetry-ext-flask/tests test-instrumentation-example-app: docs/examples/opentelemetry-example-app/tests test-instrumentation-sqlalchemy: ext/opentelemetry-ext-sqlalchemy/tests @@ -236,7 +241,7 @@ changedir = commands_pre = ; Install without -e to test the actual installation - py3{4,5,6,7}: python -m pip install -U pip setuptools wheel + py3{4,5,6,7,8}: python -m pip install -U pip setuptools wheel ; Install common packages for all the tests. These are not needed in all the ; cases but it saves a lot of boilerplate in this file. test: pip install {toxinidir}/opentelemetry-api {toxinidir}/opentelemetry-sdk {toxinidir}/tests/util @@ -252,9 +257,8 @@ commands_pre = grpc: pip install {toxinidir}/ext/opentelemetry-ext-grpc[test] - wsgi,flask,django,asgi,pyramid,starlette: pip install {toxinidir}/tests/util wsgi,flask,django,pyramid: pip install {toxinidir}/ext/opentelemetry-ext-wsgi - asgi,starlette: pip install {toxinidir}/ext/opentelemetry-ext-asgi + asgi,starlette,fastapi: pip install {toxinidir}/ext/opentelemetry-ext-asgi asyncpg: pip install {toxinidir}/ext/opentelemetry-ext-asyncpg @@ -269,6 +273,8 @@ commands_pre = django: pip install {toxinidir}/ext/opentelemetry-ext-django[test] + fastapi: pip install {toxinidir}/ext/opentelemetry-instrumentation-fastapi[test] + mysql: pip install {toxinidir}/ext/opentelemetry-ext-dbapi {toxinidir}/ext/opentelemetry-ext-mysql[test] opencensusexporter: pip install {toxinidir}/ext/opentelemetry-ext-opencensusexporter