From 1c5f0b5465e811fa2bf5fd63e491d8691de79f18 Mon Sep 17 00:00:00 2001 From: Mario Jonke Date: Wed, 31 Mar 2021 17:08:53 +0200 Subject: [PATCH] Add urllib3 instrumentation (#299) --- CHANGELOG.md | 6 +- docs/instrumentation/urllib3/urllib3.rst | 7 + .../instrumentation/requests/__init__.py | 6 +- .../instrumentation/urllib/__init__.py | 6 +- .../LICENSE | 201 ++++++++++++ .../MANIFEST.in | 9 + .../README.rst | 23 ++ .../setup.cfg | 56 ++++ .../setup.py | 31 ++ .../instrumentation/urllib3/__init__.py | 229 ++++++++++++++ .../instrumentation/urllib3/version.py | 15 + .../tests/__init__.py | 0 .../tests/test_urllib3_integration.py | 288 ++++++++++++++++++ tox.ini | 9 + 14 files changed, 879 insertions(+), 7 deletions(-) create mode 100644 docs/instrumentation/urllib3/urllib3.rst create mode 100644 instrumentation/opentelemetry-instrumentation-urllib3/LICENSE create mode 100644 instrumentation/opentelemetry-instrumentation-urllib3/MANIFEST.in create mode 100644 instrumentation/opentelemetry-instrumentation-urllib3/README.rst create mode 100644 instrumentation/opentelemetry-instrumentation-urllib3/setup.cfg create mode 100644 instrumentation/opentelemetry-instrumentation-urllib3/setup.py create mode 100644 instrumentation/opentelemetry-instrumentation-urllib3/src/opentelemetry/instrumentation/urllib3/__init__.py create mode 100644 instrumentation/opentelemetry-instrumentation-urllib3/src/opentelemetry/instrumentation/urllib3/version.py create mode 100644 instrumentation/opentelemetry-instrumentation-urllib3/tests/__init__.py create mode 100644 instrumentation/opentelemetry-instrumentation-urllib3/tests/test_urllib3_integration.py diff --git a/CHANGELOG.md b/CHANGELOG.md index f13ba6c591..1b22c6d5dd 100644 --- a/CHANGELOG.md +++ b/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.19b0...HEAD) +### Added +- `opentelemetry-instrumentation-urllib3` Add urllib3 instrumentation + ([#299](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/299)) + ## [0.19b0](https://github.com/open-telemetry/opentelemetry-python-contrib/releases/tag/v0.19b0) - 2021-03-26 ### Changed @@ -153,7 +157,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `opentelemetry-instrumentation-botocore` Make botocore instrumentation check if instrumentation has been suppressed ([#182](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/182)) - `opentelemetry-instrumentation-botocore` Botocore SpanKind as CLIENT and modify existing traced attributes - ([#150])(https://github.com/open-telemetry/opentelemetry-python-contrib/pull/150) + ([#150](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/150)) - `opentelemetry-instrumentation-dbapi` Update dbapi and its dependant instrumentations to follow semantic conventions ([#195](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/195)) - `opentelemetry-instrumentation-dbapi` Stop capturing query parameters by default diff --git a/docs/instrumentation/urllib3/urllib3.rst b/docs/instrumentation/urllib3/urllib3.rst new file mode 100644 index 0000000000..0e1e4e3326 --- /dev/null +++ b/docs/instrumentation/urllib3/urllib3.rst @@ -0,0 +1,7 @@ +OpenTelemetry urllib3 Instrumentation +============================================ + +.. automodule:: opentelemetry.instrumentation.urllib3 + :members: + :undoc-members: + :show-inheritance: diff --git a/instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/__init__.py b/instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/__init__.py index a7415a08c8..0735eba622 100644 --- a/instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/__init__.py @@ -50,7 +50,7 @@ # A key to a context variable to avoid creating duplicate spans when instrumenting # both, Session.request and Session.send, since Session.request calls into Session.send -_SUPPRESS_REQUESTS_INSTRUMENTATION_KEY = "suppress_requests_instrumentation" +_SUPPRESS_HTTP_INSTRUMENTATION_KEY = "suppress_http_instrumentation" # pylint: disable=unused-argument @@ -108,7 +108,7 @@ def _instrumented_requests_call( method: str, url: str, call_wrapped, get_or_create_headers ): if context.get_value("suppress_instrumentation") or context.get_value( - _SUPPRESS_REQUESTS_INSTRUMENTATION_KEY + _SUPPRESS_HTTP_INSTRUMENTATION_KEY ): return call_wrapped() @@ -137,7 +137,7 @@ def _instrumented_requests_call( inject(headers) token = context.attach( - context.set_value(_SUPPRESS_REQUESTS_INSTRUMENTATION_KEY, True) + context.set_value(_SUPPRESS_HTTP_INSTRUMENTATION_KEY, True) ) try: result = call_wrapped() # *** PROCEED diff --git a/instrumentation/opentelemetry-instrumentation-urllib/src/opentelemetry/instrumentation/urllib/__init__.py b/instrumentation/opentelemetry-instrumentation-urllib/src/opentelemetry/instrumentation/urllib/__init__.py index 8323053667..1ef29012af 100644 --- a/instrumentation/opentelemetry-instrumentation-urllib/src/opentelemetry/instrumentation/urllib/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-urllib/src/opentelemetry/instrumentation/urllib/__init__.py @@ -54,7 +54,7 @@ from opentelemetry.trace.status import Status # A key to a context variable to avoid creating duplicate spans when instrumenting -_SUPPRESS_URLLIB_INSTRUMENTATION_KEY = "suppress_urllib_instrumentation" +_SUPPRESS_HTTP_INSTRUMENTATION_KEY = "suppress_http_instrumentation" class URLLibInstrumentor(BaseInstrumentor): @@ -124,7 +124,7 @@ def _instrumented_open_call( _, request, call_wrapped, get_or_create_headers ): # pylint: disable=too-many-locals if context.get_value("suppress_instrumentation") or context.get_value( - _SUPPRESS_URLLIB_INSTRUMENTATION_KEY + _SUPPRESS_HTTP_INSTRUMENTATION_KEY ): return call_wrapped() @@ -154,7 +154,7 @@ def _instrumented_open_call( inject(headers) token = context.attach( - context.set_value(_SUPPRESS_URLLIB_INSTRUMENTATION_KEY, True) + context.set_value(_SUPPRESS_HTTP_INSTRUMENTATION_KEY, True) ) try: result = call_wrapped() # *** PROCEED diff --git a/instrumentation/opentelemetry-instrumentation-urllib3/LICENSE b/instrumentation/opentelemetry-instrumentation-urllib3/LICENSE new file mode 100644 index 0000000000..261eeb9e9f --- /dev/null +++ b/instrumentation/opentelemetry-instrumentation-urllib3/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + 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. diff --git a/instrumentation/opentelemetry-instrumentation-urllib3/MANIFEST.in b/instrumentation/opentelemetry-instrumentation-urllib3/MANIFEST.in new file mode 100644 index 0000000000..aed3e33273 --- /dev/null +++ b/instrumentation/opentelemetry-instrumentation-urllib3/MANIFEST.in @@ -0,0 +1,9 @@ +graft src +graft tests +global-exclude *.pyc +global-exclude *.pyo +global-exclude __pycache__/* +include CHANGELOG.md +include MANIFEST.in +include README.rst +include LICENSE diff --git a/instrumentation/opentelemetry-instrumentation-urllib3/README.rst b/instrumentation/opentelemetry-instrumentation-urllib3/README.rst new file mode 100644 index 0000000000..0332781781 --- /dev/null +++ b/instrumentation/opentelemetry-instrumentation-urllib3/README.rst @@ -0,0 +1,23 @@ +OpenTelemetry urllib3 Instrumentation +====================================== + +|pypi| + +.. |pypi| image:: https://badge.fury.io/py/opentelemetry-instrumentation-urllib3.svg + :target: https://pypi.org/project/opentelemetry-instrumentation-urllib3/ + +This library allows tracing HTTP requests made by the +`urllib3 `_ library. + +Installation +------------ + +:: + + pip install opentelemetry-instrumentation-urllib3 + +References +---------- + +* `OpenTelemetry urllib3 Instrumentation `_ +* `OpenTelemetry Project `_ diff --git a/instrumentation/opentelemetry-instrumentation-urllib3/setup.cfg b/instrumentation/opentelemetry-instrumentation-urllib3/setup.cfg new file mode 100644 index 0000000000..38f90003f1 --- /dev/null +++ b/instrumentation/opentelemetry-instrumentation-urllib3/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-urllib3 +description = OpenTelemetry urllib3 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-contrib/tree/main/instrumentation/opentelemetry-instrumentation-urllib3 +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 == 1.0.0 + opentelemetry-instrumentation == 0.19b0 + urllib3 >= 1.0.0, < 2.0.0 + wrapt >= 1.0.0, < 2.0.0 + +[options.extras_require] +test = + opentelemetry-test == 0.19b0 + httpretty ~= 1.0 + +[options.packages.find] +where = src + +[options.entry_points] +opentelemetry_instrumentor = + urllib3 = opentelemetry.instrumentation.urllib3:URLLib3Instrumentor diff --git a/instrumentation/opentelemetry-instrumentation-urllib3/setup.py b/instrumentation/opentelemetry-instrumentation-urllib3/setup.py new file mode 100644 index 0000000000..fe391cb46e --- /dev/null +++ b/instrumentation/opentelemetry-instrumentation-urllib3/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", + "urllib3", + "version.py", +) +PACKAGE_INFO = {} +with open(VERSION_FILENAME) as f: + exec(f.read(), PACKAGE_INFO) + +setuptools.setup(version=PACKAGE_INFO["__version__"]) diff --git a/instrumentation/opentelemetry-instrumentation-urllib3/src/opentelemetry/instrumentation/urllib3/__init__.py b/instrumentation/opentelemetry-instrumentation-urllib3/src/opentelemetry/instrumentation/urllib3/__init__.py new file mode 100644 index 0000000000..8c24854207 --- /dev/null +++ b/instrumentation/opentelemetry-instrumentation-urllib3/src/opentelemetry/instrumentation/urllib3/__init__.py @@ -0,0 +1,229 @@ +# 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. + +""" +This library allows tracing HTTP requests made by the +`urllib3 `_ library. + +Usage +----- +.. code-block:: python + + import urllib3 + import urllib3.util + from opentelemetry.instrumentation.urllib3 import URLLib3Instrumentor + + def strip_query_params(url: str) -> str: + return url.split("?")[0] + + def span_name_callback(method: str, url: str, headers): + return urllib3.util.Url(url).path + + URLLib3Instrumentor().instrument( + # Remove all query params from the URL attribute on the span. + url_filter=strip_query_params, + # Use the URL's path as the span name. + span_name_or_callback=span_name_callback + ) + + http = urllib3.PoolManager() + response = http.request("GET", "https://www.example.org/") + +API +--- +""" + +import contextlib +import typing + +import urllib3.connectionpool +import wrapt + +from opentelemetry import context +from opentelemetry.instrumentation.instrumentor import BaseInstrumentor +from opentelemetry.instrumentation.urllib3.version import __version__ +from opentelemetry.instrumentation.utils import ( + http_status_to_status_code, + unwrap, +) +from opentelemetry.propagate import inject +from opentelemetry.trace import Span, SpanKind, TracerProvider, get_tracer +from opentelemetry.trace.status import Status + +_SUPPRESS_HTTP_INSTRUMENTATION_KEY = "suppress_http_instrumentation" + +_UrlFilterT = typing.Optional[typing.Callable[[str], str]] +_SpanNameT = typing.Optional[ + typing.Union[typing.Callable[[str, str, typing.Mapping], str], str] +] + +_URL_OPEN_ARG_TO_INDEX_MAPPING = { + "method": 0, + "url": 1, +} + + +class URLLib3Instrumentor(BaseInstrumentor): + def _instrument(self, **kwargs): + """Instruments the urllib3 module + + Args: + **kwargs: Optional arguments + ``tracer_provider``: a TracerProvider, defaults to global. + ``span_name_or_callback``: Override the default span name. + ``url_filter``: A callback to process the requested URL prior + to adding it as a span attribute. + """ + _instrument( + tracer_provider=kwargs.get("tracer_provider"), + span_name_or_callback=kwargs.get("span_name"), + url_filter=kwargs.get("url_filter"), + ) + + def _uninstrument(self, **kwargs): + _uninstrument() + + +def _instrument( + tracer_provider: TracerProvider = None, + span_name_or_callback: _SpanNameT = None, + url_filter: _UrlFilterT = None, +): + def instrumented_urlopen(wrapped, instance, args, kwargs): + if _is_instrumentation_suppressed(): + return wrapped(*args, **kwargs) + + method = _get_url_open_arg("method", args, kwargs).upper() + url = _get_url(instance, args, kwargs, url_filter) + headers = _prepare_headers(kwargs) + + span_name = _get_span_name(span_name_or_callback, method, url, headers) + span_attributes = { + "http.method": method, + "http.url": url, + } + + with get_tracer( + __name__, __version__, tracer_provider + ).start_as_current_span( + span_name, kind=SpanKind.CLIENT, attributes=span_attributes + ) as span: + inject(headers) + + with _suppress_further_instrumentation(): + response = wrapped(*args, **kwargs) + + _apply_response(span, response) + return response + + wrapt.wrap_function_wrapper( + urllib3.connectionpool.HTTPConnectionPool, + "urlopen", + instrumented_urlopen, + ) + + +def _get_url_open_arg(name: str, args: typing.List, kwargs: typing.Mapping): + arg_idx = _URL_OPEN_ARG_TO_INDEX_MAPPING.get(name) + if arg_idx is not None: + try: + return args[arg_idx] + except IndexError: + pass + return kwargs.get(name) + + +def _get_url( + instance: urllib3.connectionpool.HTTPConnectionPool, + args: typing.List, + kwargs: typing.Mapping, + url_filter: _UrlFilterT, +) -> str: + url_or_path = _get_url_open_arg("url", args, kwargs) + if not url_or_path.startswith("/"): + url = url_or_path + else: + url = instance.scheme + "://" + instance.host + if _should_append_port(instance.scheme, instance.port): + url += ":" + str(instance.port) + url += url_or_path + + if url_filter: + return url_filter(url) + return url + + +def _should_append_port(scheme: str, port: typing.Optional[int]) -> bool: + if not port: + return False + if scheme == "http" and port == 80: + return False + if scheme == "https" and port == 443: + return False + return True + + +def _prepare_headers(urlopen_kwargs: typing.Dict) -> typing.Dict: + headers = urlopen_kwargs.get("headers") + + # avoid modifying original headers on inject + headers = headers.copy() if headers is not None else {} + urlopen_kwargs["headers"] = headers + + return headers + + +def _get_span_name( + span_name_or_callback, method: str, url: str, headers: typing.Mapping +): + span_name = None + if callable(span_name_or_callback): + span_name = span_name_or_callback(method, url, headers) + elif isinstance(span_name_or_callback, str): + span_name = span_name_or_callback + + if not span_name or not isinstance(span_name, str): + span_name = "HTTP {}".format(method.strip()) + return span_name + + +def _apply_response(span: Span, response: urllib3.response.HTTPResponse): + if not span.is_recording(): + return + + span.set_attribute("http.status_code", response.status) + span.set_attribute("http.status_text", response.reason) + span.set_status(Status(http_status_to_status_code(response.status))) + + +def _is_instrumentation_suppressed() -> bool: + return bool( + context.get_value("suppress_instrumentation") + or context.get_value(_SUPPRESS_HTTP_INSTRUMENTATION_KEY) + ) + + +@contextlib.contextmanager +def _suppress_further_instrumentation(): + token = context.attach( + context.set_value(_SUPPRESS_HTTP_INSTRUMENTATION_KEY, True) + ) + try: + yield + finally: + context.detach(token) + + +def _uninstrument(): + unwrap(urllib3.connectionpool.HTTPConnectionPool, "urlopen") diff --git a/instrumentation/opentelemetry-instrumentation-urllib3/src/opentelemetry/instrumentation/urllib3/version.py b/instrumentation/opentelemetry-instrumentation-urllib3/src/opentelemetry/instrumentation/urllib3/version.py new file mode 100644 index 0000000000..c7a4430aeb --- /dev/null +++ b/instrumentation/opentelemetry-instrumentation-urllib3/src/opentelemetry/instrumentation/urllib3/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.19b0" diff --git a/instrumentation/opentelemetry-instrumentation-urllib3/tests/__init__.py b/instrumentation/opentelemetry-instrumentation-urllib3/tests/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/instrumentation/opentelemetry-instrumentation-urllib3/tests/test_urllib3_integration.py b/instrumentation/opentelemetry-instrumentation-urllib3/tests/test_urllib3_integration.py new file mode 100644 index 0000000000..aee3d4bc0e --- /dev/null +++ b/instrumentation/opentelemetry-instrumentation-urllib3/tests/test_urllib3_integration.py @@ -0,0 +1,288 @@ +# 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 typing +from unittest import mock + +import httpretty +import urllib3 +import urllib3.exceptions + +from opentelemetry import context, trace +from opentelemetry.instrumentation.urllib3 import URLLib3Instrumentor +from opentelemetry.propagate import get_global_textmap, set_global_textmap +from opentelemetry.test.mock_textmap import MockTextMapPropagator +from opentelemetry.test.test_base import TestBase + +# pylint: disable=too-many-public-methods + + +class TestURLLib3Instrumentor(TestBase): + + HTTP_URL = "http://httpbin.org/status/200" + HTTPS_URL = "https://httpbin.org/status/200" + + def setUp(self): + super().setUp() + URLLib3Instrumentor().instrument() + + httpretty.enable(allow_net_connect=False) + httpretty.register_uri(httpretty.GET, self.HTTP_URL, body="Hello!") + httpretty.register_uri(httpretty.GET, self.HTTPS_URL, body="Hello!") + + def tearDown(self): + super().tearDown() + URLLib3Instrumentor().uninstrument() + + httpretty.disable() + httpretty.reset() + + def assert_span(self, exporter=None, num_spans=1): + if exporter is None: + exporter = self.memory_exporter + span_list = exporter.get_finished_spans() + self.assertEqual(num_spans, len(span_list)) + if num_spans == 0: + return None + if num_spans == 1: + return span_list[0] + return span_list + + def assert_success_span( + self, response: urllib3.response.HTTPResponse, url: str + ): + self.assertEqual(b"Hello!", response.data) + + span = self.assert_span() + self.assertIs(trace.SpanKind.CLIENT, span.kind) + self.assertEqual("HTTP GET", span.name) + + attributes = { + "http.method": "GET", + "http.url": url, + "http.status_code": 200, + "http.status_text": "OK", + } + self.assertEqual(attributes, span.attributes) + + def assert_exception_span(self, url: str): + span = self.assert_span() + + attributes = { + "http.method": "GET", + "http.url": url, + } + self.assertEqual(attributes, span.attributes) + self.assertEqual( + trace.status.StatusCode.ERROR, span.status.status_code + ) + + @staticmethod + def perform_request( + url: str, headers: typing.Mapping = None, retries: urllib3.Retry = None + ) -> urllib3.response.HTTPResponse: + if retries is None: + retries = urllib3.Retry.from_int(0) + + pool = urllib3.PoolManager() + return pool.request("GET", url, headers=headers, retries=retries) + + def test_basic_http_success(self): + response = self.perform_request(self.HTTP_URL) + self.assert_success_span(response, self.HTTP_URL) + + def test_basic_http_success_using_connection_pool(self): + pool = urllib3.HTTPConnectionPool("httpbin.org") + response = pool.request("GET", "/status/200") + + self.assert_success_span(response, self.HTTP_URL) + + def test_basic_https_success(self): + response = self.perform_request(self.HTTPS_URL) + self.assert_success_span(response, self.HTTPS_URL) + + def test_basic_https_success_using_connection_pool(self): + pool = urllib3.HTTPSConnectionPool("httpbin.org") + response = pool.request("GET", "/status/200") + + self.assert_success_span(response, self.HTTPS_URL) + + def test_basic_not_found(self): + url_404 = "http://httpbin.org/status/404" + httpretty.register_uri(httpretty.GET, url_404, status=404) + + response = self.perform_request(url_404) + self.assertEqual(404, response.status) + + span = self.assert_span() + self.assertEqual(404, span.attributes.get("http.status_code")) + self.assertEqual("Not Found", span.attributes.get("http.status_text")) + self.assertIs(trace.status.StatusCode.ERROR, span.status.status_code) + + def test_basic_http_non_default_port(self): + url = "http://httpbin.org:666/status/200" + httpretty.register_uri(httpretty.GET, url, body="Hello!") + + response = self.perform_request(url) + self.assert_success_span(response, url) + + def test_basic_http_absolute_url(self): + url = "http://httpbin.org:666/status/200" + httpretty.register_uri(httpretty.GET, url, body="Hello!") + pool = urllib3.HTTPConnectionPool("httpbin.org", port=666) + response = pool.request("GET", url) + + self.assert_success_span(response, url) + + def test_url_open_explicit_arg_parameters(self): + url = "http://httpbin.org:666/status/200" + httpretty.register_uri(httpretty.GET, url, body="Hello!") + pool = urllib3.HTTPConnectionPool("httpbin.org", port=666) + response = pool.urlopen(method="GET", url="/status/200") + + self.assert_success_span(response, url) + + def test_uninstrument(self): + URLLib3Instrumentor().uninstrument() + + response = self.perform_request(self.HTTP_URL) + self.assertEqual(b"Hello!", response.data) + self.assert_span(num_spans=0) + # instrument again to avoid warning message on tearDown + URLLib3Instrumentor().instrument() + + def test_suppress_instrumntation(self): + suppression_keys = ( + "suppress_instrumentation", + "suppress_http_instrumentation", + ) + for key in suppression_keys: + self.memory_exporter.clear() + + with self.subTest(key=key): + token = context.attach(context.set_value(key, True)) + try: + response = self.perform_request(self.HTTP_URL) + self.assertEqual(b"Hello!", response.data) + finally: + context.detach(token) + + self.assert_span(num_spans=0) + + def test_context_propagation(self): + previous_propagator = get_global_textmap() + try: + set_global_textmap(MockTextMapPropagator()) + response = self.perform_request(self.HTTP_URL) + self.assertEqual(b"Hello!", response.data) + + span = self.assert_span() + headers = dict(httpretty.last_request().headers) + + self.assertIn(MockTextMapPropagator.TRACE_ID_KEY, headers) + self.assertEqual( + headers[MockTextMapPropagator.TRACE_ID_KEY], + str(span.get_span_context().trace_id), + ) + self.assertIn(MockTextMapPropagator.SPAN_ID_KEY, headers) + self.assertEqual( + headers[MockTextMapPropagator.SPAN_ID_KEY], + str(span.get_span_context().span_id), + ) + finally: + set_global_textmap(previous_propagator) + + def test_custom_tracer_provider(self): + tracer_provider, exporter = self.create_tracer_provider() + tracer_provider = mock.Mock(wraps=tracer_provider) + + URLLib3Instrumentor().uninstrument() + URLLib3Instrumentor().instrument(tracer_provider=tracer_provider) + + response = self.perform_request(self.HTTP_URL) + self.assertEqual(b"Hello!", response.data) + + self.assert_span(exporter=exporter) + self.assertEqual(1, tracer_provider.get_tracer.call_count) + + @mock.patch( + "urllib3.connectionpool.HTTPConnectionPool._make_request", + side_effect=urllib3.exceptions.ConnectTimeoutError, + ) + def test_request_exception(self, _): + with self.assertRaises(urllib3.exceptions.ConnectTimeoutError): + self.perform_request( + self.HTTP_URL, retries=urllib3.Retry(connect=False) + ) + + self.assert_exception_span(self.HTTP_URL) + + @mock.patch( + "urllib3.connectionpool.HTTPConnectionPool._make_request", + side_effect=urllib3.exceptions.ProtocolError, + ) + def test_retries_do_not_create_spans(self, _): + with self.assertRaises(urllib3.exceptions.MaxRetryError): + self.perform_request(self.HTTP_URL, retries=urllib3.Retry(1)) + + # expect only a single span (retries are ignored) + self.assert_exception_span(self.HTTP_URL) + + def test_span_name_callback(self): + def span_name_callback(method, url, headers): + self.assertEqual("GET", method) + self.assertEqual(self.HTTP_URL, url) + self.assertEqual({"key": "value"}, headers) + + return "test_span_name" + + URLLib3Instrumentor().uninstrument() + URLLib3Instrumentor().instrument(span_name=span_name_callback) + + response = self.perform_request( + self.HTTP_URL, headers={"key": "value"} + ) + self.assertEqual(b"Hello!", response.data) + + span = self.assert_span() + self.assertEqual("test_span_name", span.name) + + def test_span_name_callback_invalid(self): + invalid_span_names = (None, 123, "") + + for span_name in invalid_span_names: + self.memory_exporter.clear() + + # pylint: disable=unused-argument + def span_name_callback(method, url, headers): + return span_name # pylint: disable=cell-var-from-loop + + URLLib3Instrumentor().uninstrument() + URLLib3Instrumentor().instrument(span_name=span_name_callback) + with self.subTest(span_name=span_name): + response = self.perform_request(self.HTTP_URL) + self.assertEqual(b"Hello!", response.data) + + span = self.assert_span() + self.assertEqual("HTTP GET", span.name) + + def test_url_filter(self): + def url_filter(url): + return url.split("?")[0] + + URLLib3Instrumentor().uninstrument() + URLLib3Instrumentor().instrument(url_filter=url_filter) + + response = self.perform_request(self.HTTP_URL + "?e=mcc") + self.assert_success_span(response, self.HTTP_URL) diff --git a/tox.ini b/tox.ini index 329a0f6648..54bd2abc41 100644 --- a/tox.ini +++ b/tox.ini @@ -54,6 +54,10 @@ envlist = py3{6,7,8}-test-instrumentation-urllib pypy3-test-instrumentation-urllib + ; opentelemetry-instrumentation-urllib3 + py3{6,7,8}-test-instrumentation-urllib3 + pypy3-test-instrumentation-urllib3 + ; opentelemetry-instrumentation-requests py3{6,7,8}-test-instrumentation-requests pypy3-test-instrumentation-requests @@ -182,6 +186,7 @@ changedir = test-instrumentation-fastapi: instrumentation/opentelemetry-instrumentation-fastapi/tests test-instrumentation-flask: instrumentation/opentelemetry-instrumentation-flask/tests test-instrumentation-urllib: instrumentation/opentelemetry-instrumentation-urllib/tests + test-instrumentation-urllib3: instrumentation/opentelemetry-instrumentation-urllib3/tests test-instrumentation-grpc: instrumentation/opentelemetry-instrumentation-grpc/tests test-instrumentation-jinja2: instrumentation/opentelemetry-instrumentation-jinja2/tests test-instrumentation-logging: instrumentation/opentelemetry-instrumentation-logging/tests @@ -234,6 +239,8 @@ commands_pre = urllib: pip install {toxinidir}/instrumentation/opentelemetry-instrumentation-urllib[test] + urllib3: pip install {toxinidir}/instrumentation/opentelemetry-instrumentation-urllib3[test] + botocore: pip install {toxinidir}/instrumentation/opentelemetry-instrumentation-botocore[test] dbapi: pip install {toxinidir}/instrumentation/opentelemetry-instrumentation-dbapi[test] @@ -355,6 +362,8 @@ commands_pre = python -m pip install -e {toxinidir}/instrumentation/opentelemetry-instrumentation-sqlite3[test] python -m pip install -e {toxinidir}/instrumentation/opentelemetry-instrumentation-pyramid[test] python -m pip install -e {toxinidir}/instrumentation/opentelemetry-instrumentation-requests[test] + python -m pip install -e {toxinidir}/instrumentation/opentelemetry-instrumentation-urllib[test] + python -m pip install -e {toxinidir}/instrumentation/opentelemetry-instrumentation-urllib3[test] python -m pip install -e {toxinidir}/instrumentation/opentelemetry-instrumentation-pymysql[test] python -m pip install -e {toxinidir}/instrumentation/opentelemetry-instrumentation-pymongo[test] python -m pip install -e {toxinidir}/instrumentation/opentelemetry-instrumentation-elasticsearch[test]