instruments-any

Author: jeremydvoss

CHANGELOG.md

@@ -23,7 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#3567](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3567))
 - `opentelemetry-resource-detector-containerid`: make it more quiet on platforms without cgroups
   ([#3579](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3579))
-- `opentelemetry-instrumentation`: Fix dependency conflict detection when instrumented packages are not installed by moving check back to before instrumentors are loaded. Add "instruments_either" feature for instrumentations that target multiple packages.
+- `opentelemetry-instrumentation`: Fix dependency conflict detection when instrumented packages are not installed by moving check back to before instrumentors are loaded. Add "instruments-any" feature for instrumentations that target multiple packages.
   ([#3610](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3610))
 
 ### Added

CONTRIBUTING.md

@@ -325,13 +325,13 @@ Below is a checklist of things to be mindful of when implementing a new instrume
 ### Update supported instrumentation package versions
 
 - Navigate to the **instrumentation package directory:**
-  - Update **`pyproject.toml`** file by modifying _instruments_ or _instruments_either_ entry in the `[project.optional-dependencies]` section with the new version constraint
-  - Update `_instruments` or `_instruments-either` variable in instrumentation **`package.py`** file with the new version constraint
+  - Update **`pyproject.toml`** file by modifying _instruments_ or _instruments-any_ entry in the `[project.optional-dependencies]` section with the new version constraint
+  - Update `_instruments` or `_instruments-any` variable in instrumentation **`package.py`** file with the new version constraint
 - At the **root of the project directory**, run `tox -e generate` to regenerate necessary files
 
-Please note that _instruments_either_ is an optional field that can be used instead of or in addition to _instruments_. While _instruments_ is a list of dependencies, _all_ of which are expected by the instrumentation, _instruments_either_ is a list _any_ of which but not all are expected.
+Please note that _instruments-any_ is an optional field that can be used instead of or in addition to _instruments_. While _instruments_ is a list of dependencies, _all_ of which are expected by the instrumentation, _instruments-any_ is a list _any_ of which but not all are expected.
 
-<!-- See https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3610 for details on instruments_either -->
+<!-- See https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3610 for details on instruments-any -->
 
 If you're adding support for a new version of the instrumentation package, follow these additional steps:
 

opentelemetry-instrumentation/src/opentelemetry/instrumentation/dependencies.py

@@ -40,33 +40,33 @@ class DependencyConflict:
     Attributes:
         required: The required dependency specification that conflicts with what's installed.
         found: The actual dependency that was found installed (if any).
-        required_either: Collection of dependency specifications where any one would satisfy
+        required_any: Collection of dependency specifications where any one would satisfy
             the requirement (for either/or scenarios).
-        found_either: Collection of actual dependencies found for either/or scenarios.
+        found_any: Collection of actual dependencies found for either/or scenarios.
     """
 
     required: str | None = None
     found: str | None = None
     # The following fields are used when an instrumentation requires any of a set of dependencies rather than all.
-    required_either: Collection[str] = None
-    found_either: Collection[str] = None
+    required_any: Collection[str] = None
+    found_any: Collection[str] = None
 
     def __init__(
         self,
         required: str | None = None,
         found: str | None = None,
-        required_either: Collection[str] = None,
-        found_either: Collection[str] = None,
+        required_any: Collection[str] = None,
+        found_any: Collection[str] = None,
     ):
         self.required = required
         self.found = found
         # The following fields are used when an instrumentation requires any of a set of dependencies rather than all.
-        self.required_either = required_either
-        self.found_either = found_either
+        self.required_any = required_any
+        self.found_any = found_any
 
     def __str__(self):
-        if not self.required and (self.required_either or self.found_either):
-            return f'DependencyConflict: requested any of the following: "{self.required_either}" but found: "{self.found_either}"'
+        if not self.required and (self.required_any or self.found_any):
+            return f'DependencyConflict: requested any of the following: "{self.required_any}" but found: "{self.found_any}"'
         return f'DependencyConflict: requested: "{self.required}" but found: "{self.found}"'
 
 
@@ -84,34 +84,34 @@ def get_dist_dependency_conflicts(
     dist: Distribution,
 ) -> DependencyConflict | None:
     instrumentation_deps = []
-    instrumentation_either_deps = []
+    instrumentation_any_deps = []
     extra = "extra"
     instruments = "instruments"
     instruments_marker = {extra: instruments}
-    instruments_either = "instruments_either"
-    instruments_either_marker = {extra: instruments_either}
+    instruments_any = "instruments-any"
+    instruments_any_marker = {extra: instruments_any}
     if dist.requires:
         for dep in dist.requires:
             if extra not in dep:
                 continue
-            if instruments not in dep and instruments_either not in dep:
+            if instruments not in dep and instruments_any not in dep:
                 continue
 
             req = Requirement(dep)
             if req.marker.evaluate(instruments_marker):  # type: ignore
                 instrumentation_deps.append(req)  # type: ignore
-            if req.marker.evaluate(instruments_either_marker):  # type: ignore
-                instrumentation_either_deps.append(req)  # type: ignore
+            if req.marker.evaluate(instruments_any_marker):  # type: ignore
+                instrumentation_any_deps.append(req)  # type: ignore
     return get_dependency_conflicts(
-        instrumentation_deps, instrumentation_either_deps
+        instrumentation_deps, instrumentation_any_deps
     )  # type: ignore
 
 
 def get_dependency_conflicts(
     deps: Collection[
         str | Requirement
     ],  # Dependencies all of which are required
-    deps_either: Collection[
+    deps_any: Collection[
         str | Requirement
     ] = None,  # Dependencies any of which are required
 ) -> DependencyConflict | None:
@@ -137,22 +137,22 @@ def get_dependency_conflicts(
         if not req.specifier.contains(dist_version):
             return DependencyConflict(dep, f"{req.name} {dist_version}")
 
-    # If all the dependencies in "instruments" are present, check "instruments_either" for conflicts.
-    if deps_either:
-        return _get_dependency_conflicts_either(deps_either)
+    # If all the dependencies in "instruments" are present, check "instruments-any" for conflicts.
+    if deps_any:
+        return _get_dependency_conflicts_any(deps_any)
     return None
 
 
 # This is a helper functions designed to ease reading and meet linting requirements.
-def _get_dependency_conflicts_either(
-    deps_either: Collection[str | Requirement],
+def _get_dependency_conflicts_any(
+    deps_any: Collection[str | Requirement],
 ) -> DependencyConflict | None:
-    if not deps_either:
+    if not deps_any:
         return None
     is_dependency_conflict = True
-    required_either: Collection[str] = []
-    found_either: Collection[str] = []
-    for dep in deps_either:
+    required_any: Collection[str] = []
+    found_any: Collection[str] = []
+    for dep in deps_any:
         if isinstance(dep, Requirement):
             req = dep
         else:
@@ -169,20 +169,20 @@ def _get_dependency_conflicts_either(
         try:
             dist_version = version(req.name)
         except PackageNotFoundError:
-            required_either.append(str(dep))
+            required_any.append(str(dep))
             continue
 
         if req.specifier.contains(dist_version):
-            # Since only one of the instrumentation_either dependencies is required, there is no dependency conflict.
+            # Since only one of the instrumentation_any dependencies is required, there is no dependency conflict.
             is_dependency_conflict = False
             break
         # If the version does not match, add it to the list of unfulfilled requirement options.
-        required_either.append(str(dep))
-        found_either.append(f"{req.name} {dist_version}")
+        required_any.append(str(dep))
+        found_any.append(f"{req.name} {dist_version}")
 
     if is_dependency_conflict:
         return DependencyConflict(
-            required_either=required_either,
-            found_either=found_either,
+            required_any=required_any,
+            found_any=found_any,
         )
     return None

opentelemetry-instrumentation/tests/test_dependencies.py

@@ -110,7 +110,7 @@ def requires(self):
         self.assertTrue(conflict is None)
 
     @patch("opentelemetry.instrumentation.dependencies.version")
-    def test_get_dist_dependency_conflicts_either(self, version_mock):
+    def test_get_dist_dependency_conflicts_any(self, version_mock):
         class MockDistribution(Distribution):
             def locate_file(self, path):
                 pass
@@ -121,8 +121,8 @@ def read_text(self, filename):
             @property
             def requires(self):
                 return [
-                    'foo ~= 1.0; extra == "instruments_either"',
-                    'bar ~= 1.0; extra == "instruments_either"',
+                    'foo ~= 1.0; extra == "instruments-any"',
+                    'bar ~= 1.0; extra == "instruments-any"',
                 ]
 
         dist = MockDistribution()
@@ -150,8 +150,8 @@ def read_text(self, filename):
             @property
             def requires(self):
                 return [
-                    'foo ~= 1.0; extra == "instruments_either"',
-                    'bar ~= 1.0; extra == "instruments_either"',
+                    'foo ~= 1.0; extra == "instruments-any"',
+                    'bar ~= 1.0; extra == "instruments-any"',
                 ]
 
         dist = MockDistribution()
@@ -163,12 +163,12 @@ def requires(self):
         self.assertTrue(isinstance(conflict, DependencyConflict))
         self.assertEqual(
             str(conflict),
-            '''DependencyConflict: requested any of the following: "['foo~=1.0; extra == "instruments-either"', 'bar~=1.0; extra == "instruments-either"']" but found: "[]"''',
+            '''DependencyConflict: requested any of the following: "['foo~=1.0; extra == "instruments-any"', 'bar~=1.0; extra == "instruments-any"']" but found: "[]"''',
         )
 
     # Tests when both "and" and "either" dependencies are specified and both pass.
     @patch("opentelemetry.instrumentation.dependencies.version")
-    def test_get_dist_dependency_conflicts_either_and(self, version_mock):
+    def test_get_dist_dependency_conflicts_any_and(self, version_mock):
         class MockDistribution(Distribution):
             def locate_file(self, path):
                 pass
@@ -181,8 +181,8 @@ def requires(self):
                 # This indicates the instrumentation requires (foo and (bar or baz)))
                 return [
                     'foo ~= 1.0; extra == "instruments"',
-                    'bar ~= 2.0; extra == "instruments_either"',
-                    'baz ~= 3.0; extra == "instruments_either"',
+                    'bar ~= 2.0; extra == "instruments-any"',
+                    'baz ~= 3.0; extra == "instruments-any"',
                 ]
 
         dist = MockDistribution()
@@ -202,9 +202,7 @@ def version_side_effect(package_name):
 
     # Tests when both "and" and "either" dependencies are specified but the "and" dependencies fail to resolve.
     @patch("opentelemetry.instrumentation.dependencies.version")
-    def test_get_dist_dependency_conflicts_either_and_failed(
-        self, version_mock
-    ):
+    def test_get_dist_dependency_conflicts_any_and_failed(self, version_mock):
         class MockDistribution(Distribution):
             def locate_file(self, path):
                 pass
@@ -217,8 +215,8 @@ def requires(self):
                 # This indicates the instrumentation requires (foo and (bar or baz)))
                 return [
                     'foo ~= 1.0; extra == "instruments"',
-                    'bar ~= 2.0; extra == "instruments_either"',
-                    'baz ~= 3.0; extra == "instruments_either"',
+                    'bar ~= 2.0; extra == "instruments-any"',
+                    'baz ~= 3.0; extra == "instruments-any"',
                 ]
 
         dist = MockDistribution()
@@ -243,9 +241,7 @@ def version_side_effect(package_name):
 
     # Tests when both "and" and "either" dependencies are specified but the "either" dependencies fail to resolve.
     @patch("opentelemetry.instrumentation.dependencies.version")
-    def test_get_dist_dependency_conflicts_and_either_failed(
-        self, version_mock
-    ):
+    def test_get_dist_dependency_conflicts_and_any_failed(self, version_mock):
         class MockDistribution(Distribution):
             def locate_file(self, path):
                 pass
@@ -258,8 +254,8 @@ def requires(self):
                 # This indicates the instrumentation requires (foo and (bar or baz)))
                 return [
                     'foo ~= 1.0; extra == "instruments"',
-                    'bar ~= 2.0; extra == "instruments_either"',
-                    'baz ~= 3.0; extra == "instruments_either"',
+                    'bar ~= 2.0; extra == "instruments-any"',
+                    'baz ~= 3.0; extra == "instruments-any"',
                 ]
 
         dist = MockDistribution()
@@ -279,5 +275,5 @@ def version_side_effect(package_name):
         self.assertTrue(isinstance(conflict, DependencyConflict))
         self.assertEqual(
             str(conflict),
-            '''DependencyConflict: requested any of the following: "['bar~=2.0; extra == "instruments-either"', 'baz~=3.0; extra == "instruments-either"']" but found: "[]"''',
+            '''DependencyConflict: requested any of the following: "['bar~=2.0; extra == "instruments-any"', 'baz~=3.0; extra == "instruments-any"']" but found: "[]"''',
         )

scripts/generate_instrumentation_bootstrap.py

@@ -84,7 +84,7 @@ def main():
         pkg_name = pkg.get("name")
         if pkg_name in packages_to_exclude:
             continue
-        if not pkg["instruments"] and not pkg["instruments_either"]:
+        if not pkg["instruments"] and not pkg["instruments-any"]:
             default_instrumentations.elts.append(ast.Str(pkg["requirement"]))
         for target_pkg in pkg["instruments"]:
             libraries.elts.append(
@@ -93,8 +93,8 @@ def main():
                     values=[ast.Str(target_pkg), ast.Str(pkg["requirement"])],
                 )
             )
-        # _instruments_either is an optional field that can be used instead of or in addition to _instruments. While _instruments is a list of dependencies, all of which are expected by the instrumentation, _instruments_either is a list any of which but not all are expected.
-        for target_pkg in pkg["instruments_either"]:
+        # _instruments-any is an optional field that can be used instead of or in addition to _instruments. While _instruments is a list of dependencies, all of which are expected by the instrumentation, _instruments-any is a list any of which but not all are expected.
+        for target_pkg in pkg["instruments-any"]:
             libraries.elts.append(
                 ast.Dict(
                     keys=[ast.Str("library"), ast.Str("instrumentation")],

scripts/generate_instrumentation_readme.py

@@ -59,15 +59,15 @@ def main(base_instrumentation_path):
             exec(fh.read(), pkg_info)
 
         instruments_and = pkg_info.get("_instruments", ())
-        # _instruments_either is an optional field that can be used instead of or in addition to _instruments. While _instruments is a list of dependencies, all of which are expected by the instrumentation, _instruments_either is a list any of which but not all are expected.
-        instruments_either = pkg_info.get("_instruments_either", ())
+        # _instruments-any is an optional field that can be used instead of or in addition to _instruments. While _instruments is a list of dependencies, all of which are expected by the instrumentation, _instruments-any is a list any of which but not all are expected.
+        instruments_any = pkg_info.get("_instruments-any", ())
         supports_metrics = pkg_info.get("_supports_metrics")
         semconv_status = pkg_info.get("_semconv_status")
         instruments_all = ()
-        if not instruments_and and not instruments_either:
+        if not instruments_and and not instruments_any:
             instruments_all = (name,)
         else:
-            instruments_all = tuple(instruments_and + instruments_either)
+            instruments_all = tuple(instruments_and + instruments_any)
 
         if not semconv_status:
             semconv_status = "development"

scripts/otel_packaging.py

@@ -64,15 +64,13 @@ def get_instrumentation_packages(
             "optional-dependencies"
         ]
         instruments = optional_dependencies.get("instruments", [])
-        # _instruments_either is an optional field that can be used instead of or in addition to _instruments. While _instruments is a list of dependencies, all of which are expected by the instrumentation, _instruments_either is a list any of which but not all are expected.
-        instruments_either = optional_dependencies.get(
-            "instruments_either", []
-        )
+        # _instruments-any is an optional field that can be used instead of or in addition to _instruments. While _instruments is a list of dependencies, all of which are expected by the instrumentation, _instruments-any is a list any of which but not all are expected.
+        instruments_any = optional_dependencies.get("instruments-any", [])
         instrumentation = {
             "name": pyproject_toml["project"]["name"],
             "version": version.strip(),
             "instruments": instruments,
-            "instruments_either": instruments_either,
+            "instruments-any": instruments_any,
         }
         if instrumentation["name"] in independent_packages:
             specifier = independent_packages[instrumentation["name"]]