feat(sdk): add MissingDependencyError for declarative configuration (#5265)

* feat(sdk): add MissingDependencyError for declarative configuration dependency checking

Implements a structured MissingDependencyError (subclass of ConfigurationError)
that generates a descriptive pip install message. Replaces ad-hoc
ConfigurationError / ImportError raises across all declarative config
providers (tracer, logger, meter, file loader) for missing optional
dependencies like OTLP exporters, Prometheus reader, pyyaml, and
jsonschema.

Adds unit tests covering the new exception class.

Closes #5229

* fix: address PR #5265 review comments

- Rename .changelog/5229.added -> .changelog/5265.added
- Make MissingDependencyError inherit from both ConfigurationError and ImportError
- Add docstring hints for constructor parameters
- Use double quotes in pip install command for Windows compatibility

Assisted-by: Claude

* remove unnecessary test

---------

Co-authored-by: Mike Goldsmith <goldsmith.mike@gmail.com>

Author: dharaneeshexe-web

.changelog/5265.added

@@ -0,0 +1 @@
+`opentelemetry-sdk`: add `MissingDependencyError` exception for declarative configuration and use it for missing optional dependency errors

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_exceptions.py

@@ -12,3 +12,48 @@ class ConfigurationError(Exception):
     - Environment variable substitution errors
     - Missing required SDK extensions (e.g., propagator packages not installed)
     """
+
+
+class MissingDependencyError(ConfigurationError, ImportError):
+    """Raised when an optional dependency is not installed.
+
+    Inherits from both :class:`ConfigurationError` and :class:`ImportError` to
+    maintain backwards compatibility with callers that catch ``ImportError``.
+
+    Args:
+        package: The name of the missing package.
+        feature: Optional description of the feature that requires the package.
+        install_name: Optional package name used in the pip install command
+            (defaults to ``package``).
+        extras: Optional extras string for the pip install command.
+    """
+
+    def __init__(
+        self,
+        package: str,
+        feature: str | None = None,
+        install_name: str | None = None,
+        extras: str | None = None,
+    ) -> None:
+        self.package = package
+        self.feature = feature
+        self.install_name = install_name or package
+        self.extras = extras
+
+        if extras:
+            install_cmd = f'pip install "{self.install_name}[{extras}]"'
+        else:
+            install_cmd = f"pip install {self.install_name}"
+
+        if feature:
+            message = (
+                f"{feature} requires '{package}'. "
+                f"Install it with: {install_cmd}"
+            )
+        else:
+            message = (
+                f"'{package}' is required but not installed. "
+                f"Install it with: {install_cmd}"
+            )
+
+        super().__init__(message)

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_logger_provider.py

@@ -12,7 +12,10 @@
     _parse_otlp_file_output_stream,
     load_entry_point,
 )
-from opentelemetry.sdk._configuration._exceptions import ConfigurationError
+from opentelemetry.sdk._configuration._exceptions import (
+    ConfigurationError,
+    MissingDependencyError,
+)
 from opentelemetry.sdk._configuration.models import (
     BatchLogRecordProcessor as BatchLogRecordProcessorConfig,
 )
@@ -73,9 +76,9 @@ def _create_otlp_http_log_exporter(
             OTLPLogExporter,
         )
     except ImportError as exc:
-        raise ConfigurationError(
-            "otlp_http log exporter requires 'opentelemetry-exporter-otlp-proto-http'. "
-            "Install it with: pip install opentelemetry-exporter-otlp-proto-http"
+        raise MissingDependencyError(
+            package="opentelemetry-exporter-otlp-proto-http",
+            feature="otlp_http log exporter",
         ) from exc
 
     compression = _map_compression(
@@ -104,9 +107,9 @@ def _create_otlp_grpc_log_exporter(
             OTLPLogExporter,
         )
     except ImportError as exc:
-        raise ConfigurationError(
-            "otlp_grpc log exporter requires 'opentelemetry-exporter-otlp-proto-grpc'. "
-            "Install it with: pip install opentelemetry-exporter-otlp-proto-grpc"
+        raise MissingDependencyError(
+            package="opentelemetry-exporter-otlp-proto-grpc",
+            feature="otlp_grpc log exporter",
         ) from exc
 
     compression = _map_compression(config.compression, grpc.Compression)

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_meter_provider.py

@@ -12,7 +12,10 @@
     _parse_otlp_file_output_stream,
     load_entry_point,
 )
-from opentelemetry.sdk._configuration._exceptions import ConfigurationError
+from opentelemetry.sdk._configuration._exceptions import (
+    ConfigurationError,
+    MissingDependencyError,
+)
 from opentelemetry.sdk._configuration.models import (
     Aggregation as AggregationConfig,
 )
@@ -283,9 +286,9 @@ def _create_otlp_http_metric_exporter(
             OTLPMetricExporter,
         )
     except ImportError as exc:
-        raise ConfigurationError(
-            "otlp_http metric exporter requires 'opentelemetry-exporter-otlp-proto-http'. "
-            "Install it with: pip install opentelemetry-exporter-otlp-proto-http"
+        raise MissingDependencyError(
+            package="opentelemetry-exporter-otlp-proto-http",
+            feature="otlp_http metric exporter",
         ) from exc
 
     compression = _map_compression(
@@ -320,9 +323,9 @@ def _create_otlp_grpc_metric_exporter(
             OTLPMetricExporter,
         )
     except ImportError as exc:
-        raise ConfigurationError(
-            "otlp_grpc metric exporter requires 'opentelemetry-exporter-otlp-proto-grpc'. "
-            "Install it with: pip install opentelemetry-exporter-otlp-proto-grpc"
+        raise MissingDependencyError(
+            package="opentelemetry-exporter-otlp-proto-grpc",
+            feature="otlp_grpc metric exporter",
         ) from exc
 
     compression = _map_compression(config.compression, grpc.Compression)
@@ -451,10 +454,9 @@ def _create_prometheus_metric_reader(
             start_http_server,
         )
     except ImportError as exc:
-        raise ConfigurationError(
-            "prometheus pull metric exporter requires "
-            "'opentelemetry-exporter-prometheus'. "
-            "Install it with: pip install opentelemetry-exporter-prometheus"
+        raise MissingDependencyError(
+            package="opentelemetry-exporter-prometheus",
+            feature="prometheus pull metric exporter",
         ) from exc
 
     disable_target_info = (

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_tracer_provider.py

@@ -12,7 +12,10 @@
     _parse_otlp_file_output_stream,
     load_entry_point,
 )
-from opentelemetry.sdk._configuration._exceptions import ConfigurationError
+from opentelemetry.sdk._configuration._exceptions import (
+    ConfigurationError,
+    MissingDependencyError,
+)
 from opentelemetry.sdk._configuration.models import (
     ExperimentalComposableRuleBasedSampler as RuleBasedSamplerConfig,
 )
@@ -116,9 +119,9 @@ def _create_otlp_http_span_exporter(
             OTLPSpanExporter,
         )
     except ImportError as exc:
-        raise ConfigurationError(
-            "otlp_http span exporter requires 'opentelemetry-exporter-otlp-proto-http'. "
-            "Install it with: pip install opentelemetry-exporter-otlp-proto-http"
+        raise MissingDependencyError(
+            package="opentelemetry-exporter-otlp-proto-http",
+            feature="otlp_http span exporter",
         ) from exc
 
     compression = _map_compression(
@@ -147,9 +150,9 @@ def _create_otlp_grpc_span_exporter(
             OTLPSpanExporter,
         )
     except ImportError as exc:
-        raise ConfigurationError(
-            "otlp_grpc span exporter requires 'opentelemetry-exporter-otlp-proto-grpc'. "
-            "Install it with: pip install opentelemetry-exporter-otlp-proto-grpc"
+        raise MissingDependencyError(
+            package="opentelemetry-exporter-otlp-proto-grpc",
+            feature="otlp_grpc span exporter",
         ) from exc
 
     compression = _map_compression(config.compression, grpc.Compression)

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/file/__init__.py

@@ -13,7 +13,10 @@
     '1.0'
 """
 
-from opentelemetry.sdk._configuration._exceptions import ConfigurationError
+from opentelemetry.sdk._configuration._exceptions import (
+    ConfigurationError,
+    MissingDependencyError,
+)
 from opentelemetry.sdk._configuration._logger_provider import (
     configure_logger_provider,
     create_logger_provider,
@@ -43,6 +46,7 @@
     "configure_sdk",
     "substitute_env_vars",
     "ConfigurationError",
+    "MissingDependencyError",
     "EnvSubstitutionError",
     "create_resource",
     "create_propagator",

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/file/_loader.py

@@ -11,7 +11,10 @@
 from typing import Any
 
 from opentelemetry.sdk._configuration._conversion import _dict_to_dataclass
-from opentelemetry.sdk._configuration._exceptions import ConfigurationError
+from opentelemetry.sdk._configuration._exceptions import (
+    ConfigurationError,
+    MissingDependencyError,
+)
 from opentelemetry.sdk._configuration.file._env_substitution import (
     substitute_env_vars,
 )
@@ -20,17 +23,21 @@
 try:
     import yaml
 except ImportError as exc:
-    raise ImportError(
-        "File configuration requires pyyaml. "
-        "Install with: pip install opentelemetry-sdk[file-configuration]"
+    raise MissingDependencyError(
+        package="pyyaml",
+        feature="File configuration",
+        install_name="opentelemetry-sdk",
+        extras="file-configuration",
     ) from exc
 
 try:
     import jsonschema
 except ImportError as exc:
-    raise ImportError(
-        "File configuration requires jsonschema. "
-        "Install with: pip install opentelemetry-sdk[file-configuration]"
+    raise MissingDependencyError(
+        package="jsonschema",
+        feature="File configuration",
+        install_name="opentelemetry-sdk",
+        extras="file-configuration",
     ) from exc
 
 # Schema version vendored in schema.json. ``file_format`` values are accepted

opentelemetry-sdk/tests/_configuration/test_exceptions.py

@@ -0,0 +1,74 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+import unittest
+
+from opentelemetry.sdk._configuration._exceptions import (
+    ConfigurationError,
+    MissingDependencyError,
+)
+
+
+class TestMissingDependencyError(unittest.TestCase):
+    def test_is_configuration_error_subclass(self):
+        self.assertTrue(issubclass(MissingDependencyError, ConfigurationError))
+
+    def test_minimal_constructor(self):
+        exc = MissingDependencyError(package="foo")
+        self.assertEqual(exc.package, "foo")
+        self.assertIsNone(exc.feature)
+        self.assertEqual(exc.install_name, "foo")
+        self.assertIsNone(exc.extras)
+        self.assertIn("'foo'", str(exc))
+        self.assertIn("pip install foo", str(exc))
+
+    def test_with_feature(self):
+        exc = MissingDependencyError(package="bar", feature="Baz exporter")
+        self.assertEqual(exc.package, "bar")
+        self.assertEqual(exc.feature, "Baz exporter")
+        self.assertIn("Baz exporter requires 'bar'", str(exc))
+        self.assertIn("pip install bar", str(exc))
+
+    def test_with_custom_install_name(self):
+        exc = MissingDependencyError(
+            package="pyyaml",
+            install_name="opentelemetry-sdk",
+            extras="file-configuration",
+        )
+        self.assertEqual(exc.install_name, "opentelemetry-sdk")
+        self.assertEqual(exc.extras, "file-configuration")
+        self.assertIn(
+            'pip install "opentelemetry-sdk[file-configuration]"', str(exc)
+        )
+
+    def test_with_feature_and_extras(self):
+        exc = MissingDependencyError(
+            package="jsonschema",
+            feature="File configuration",
+            install_name="opentelemetry-sdk",
+            extras="file-configuration",
+        )
+        self.assertIn("File configuration requires 'jsonschema'", str(exc))
+        self.assertIn(
+            'pip install "opentelemetry-sdk[file-configuration]"', str(exc)
+        )
+
+    def test_can_be_caught_as_configuration_error(self):
+        with self.assertRaises(ConfigurationError):
+            raise MissingDependencyError(package="test")
+
+    def test_can_be_caught_as_exception(self):
+        with self.assertRaises(Exception):
+            raise MissingDependencyError(package="test")
+
+    def test_can_be_caught_as_import_error(self):
+        with self.assertRaises(ImportError):
+            raise MissingDependencyError(package="test")
+
+    def test_is_import_error_subclass(self):
+        self.assertTrue(issubclass(MissingDependencyError, ImportError))
+
+    def test_issubclass_import_error(self):
+        self.assertIsInstance(
+            MissingDependencyError(package="test"), ImportError
+        )