From 2ea49330a0a41f14edb9c272d450affdc27b193e Mon Sep 17 00:00:00 2001 From: Erica Pisani Date: Fri, 20 Nov 2026 10:56:30 -0500 Subject: [PATCH 1/2] feat(integrations): Defer OpenAI integration setup until openai is imported Behind the deferred_auto_enabling_integrations experiment, init() no longer imports openai just because the OpenAI integration is auto-enabling. A sys.meta_path finder wraps the openai loader and sets the integration up once the application imports openai itself. Integrations not in the trigger mapping keep the eager setup. Refs TEL-133 --- sentry_sdk/consts.py | 1 + sentry_sdk/integrations/__init__.py | 168 ++++++++++++++++++++++- tests/integrations/openai/test_openai.py | 59 ++++++++ 3 files changed, 221 insertions(+), 7 deletions(-) diff --git a/sentry_sdk/consts.py b/sentry_sdk/consts.py index 3d89c260f3..3fd69def01 100644 --- a/sentry_sdk/consts.py +++ b/sentry_sdk/consts.py @@ -91,6 +91,7 @@ class CompressionAlgo(Enum): ], "suppress_asgi_chained_exceptions": Optional[bool], "data_collection": Optional[DataCollectionUserOptions], + "deferred_auto_enabling_integrations": Optional[bool], }, total=False, ) diff --git a/sentry_sdk/integrations/__init__.py b/sentry_sdk/integrations/__init__.py index 4cd4595c5f..8e26a4e216 100644 --- a/sentry_sdk/integrations/__init__.py +++ b/sentry_sdk/integrations/__init__.py @@ -1,14 +1,31 @@ +import importlib.util +import sys from abc import ABC, abstractmethod from importlib import import_module +from importlib.abc import Loader, MetaPathFinder from itertools import zip_longest -from threading import Lock +from threading import Lock, local from typing import TYPE_CHECKING -from sentry_sdk.utils import logger +import sentry_sdk +from sentry_sdk.utils import capture_internal_exceptions, logger if TYPE_CHECKING: - from collections.abc import Sequence - from typing import Any, Callable, Dict, Iterator, List, Optional, Set, Type, Union + from collections.abc import Container, Sequence + from importlib.machinery import ModuleSpec + from types import ModuleType + from typing import ( + Any, + Callable, + Dict, + Iterator, + List, + Optional, + Set, + Tuple, + Type, + Union, + ) _DEFAULT_FAILED_REQUEST_STATUS_CODES = frozenset(range(500, 600)) @@ -22,13 +39,20 @@ # Set of all integration identifiers we have actually installed _installed_integrations: "Set[str]" = set() +# Trigger module -> (integration import string, client options) of deferred +# integrations waiting for the application to import the trigger module +_pending_deferred_integrations: "Dict[str, Tuple[str, Optional[Dict[str, Any]]]]" = {} + +_deferred_setup_finder_guard = local() + def _generate_default_integrations_iterator( integrations: "List[str]", auto_enabling_integrations: "List[str]", -) -> "Callable[[bool], Iterator[Type[Integration]]]": +) -> "Callable[..., Iterator[Type[Integration]]]": def iter_default_integrations( with_auto_enabling_integrations: bool, + exclude: "Container[str]" = (), ) -> "Iterator[Type[Integration]]": """Returns an iterator of the default integration classes:""" if with_auto_enabling_integrations: @@ -37,6 +61,8 @@ def iter_default_integrations( all_import_strings = integrations for import_string in all_import_strings: + if import_string in exclude: + continue try: module, cls = import_string.rsplit(".", 1) yield getattr(import_module(module), cls) @@ -108,6 +134,13 @@ def iter_default_integrations( "sentry_sdk.integrations.tornado.TornadoIntegration", ] +# With the `deferred_auto_enabling_integrations` experiment on, these auto-enabling +# integrations are only set up once the application imports the trigger module. +# This can't live on the integration class, since loading the class imports the library. +_DEFERRED_INTEGRATION_TRIGGERS = { + "sentry_sdk.integrations.openai.OpenAIIntegration": "openai", +} + iter_default_integrations = _generate_default_integrations_iterator( integrations=_DEFAULT_INTEGRATIONS, auto_enabling_integrations=_AUTO_ENABLING_INTEGRATIONS, @@ -210,6 +243,22 @@ def setup_integrations( logger.debug("Setting up integrations (with default = %s)", with_defaults) + deferred: "Dict[str, Optional[str]]" = {} + if ( + with_defaults + and with_auto_enabling_integrations + and options is not None + and options["_experiments"].get("deferred_auto_enabling_integrations") + ): + for import_string, trigger in _DEFERRED_INTEGRATION_TRIGGERS.items(): + if trigger in sys.modules: + continue + spec = importlib.util.find_spec(trigger) + if spec is None: + deferred[import_string] = None + elif hasattr(spec.loader, "exec_module"): + deferred[import_string] = trigger + user_provided_integrations = set(integrations.keys()) # Integrations that will not be enabled @@ -223,7 +272,7 @@ def setup_integrations( if with_defaults: for integration_cls in iter_default_integrations( - with_auto_enabling_integrations + with_auto_enabling_integrations, exclude=deferred ): if integration_cls.identifier not in integrations: instance = integration_cls() @@ -233,6 +282,7 @@ def setup_integrations( disabled_integration_identifiers = { integration.identifier for integration in disabled_integrations } + deactivated_identifiers = set() for integration, targets_to_deactivate in _INTEGRATION_DEACTIVATES.items(): if ( @@ -241,7 +291,8 @@ def setup_integrations( ): for target in targets_to_deactivate: if target not in user_provided_integrations: - for cls in iter_default_integrations(True): + deactivated_identifiers.add(target) + for cls in iter_default_integrations(True, exclude=deferred): if cls.identifier == target: if cls not in disabled_integrations: disabled_integrations.append(cls) @@ -275,6 +326,29 @@ def setup_integrations( _processed_integrations.add(identifier) + for import_string, trigger in deferred.items(): + identifier = import_string.rsplit(".", 2)[1] + if ( + trigger is None + or identifier in disabled_integration_identifiers + or identifier in deactivated_identifiers + ): + continue + + with _installer_lock: + if identifier in _processed_integrations: + continue + _processed_integrations.add(identifier) + _pending_deferred_integrations[trigger] = (import_string, options) + if _deferred_setup_finder not in sys.meta_path: + sys.meta_path.insert(0, _deferred_setup_finder) + + logger.debug( + "Deferring setup of integration %s until %s is imported", + identifier, + trigger, + ) + integrations = { identifier: integration for identifier, integration in integrations.items() @@ -287,6 +361,86 @@ def setup_integrations( return integrations +def _set_up_deferred_integration(trigger: str) -> None: + with _installer_lock: + pending = _pending_deferred_integrations.pop(trigger, None) + if ( + not _pending_deferred_integrations + and _deferred_setup_finder in sys.meta_path + ): + sys.meta_path.remove(_deferred_setup_finder) + + if pending is None: + return + + import_string, options = pending + with capture_internal_exceptions(): + module, cls = import_string.rsplit(".", 1) + try: + integration = getattr(import_module(module), cls)() + type(integration).setup_once() + integration.setup_once_with_options(options) + except DidNotEnable as e: + logger.debug("Did not enable default integration %s: %s", import_string, e) + return + + _installed_integrations.add(integration.identifier) + sentry_sdk.get_client().integrations[integration.identifier] = integration + logger.debug("Enabling integration %s", integration.identifier) + + +class _DeferredSetupLoader(Loader): + def __init__(self, loader: "Any", trigger: str) -> None: + self._loader = loader + self._trigger = trigger + + def create_module(self, spec: "ModuleSpec") -> "Optional[ModuleType]": + return self._loader.create_module(spec) + + def exec_module(self, module: "ModuleType") -> None: + self._loader.exec_module(module) + module.__loader__ = self._loader + if module.__spec__ is not None: + module.__spec__.loader = self._loader + _set_up_deferred_integration(self._trigger) + + def __getattr__(self, name: str) -> "Any": + return getattr(self._loader, name) + + +class _DeferredSetupFinder(MetaPathFinder): + def find_spec( + self, + fullname: str, + path: "Optional[Sequence[str]]" = None, + target: "Optional[ModuleType]" = None, + ) -> "Optional[ModuleSpec]": + if fullname not in _pending_deferred_integrations or getattr( + _deferred_setup_finder_guard, "active", False + ): + return None + + _deferred_setup_finder_guard.active = True + try: + for finder in sys.meta_path: + if finder is self or not hasattr(finder, "find_spec"): + continue + spec = finder.find_spec(fullname, path, target) + if spec is not None: + break + else: + return None + finally: + _deferred_setup_finder_guard.active = False + + if hasattr(spec.loader, "exec_module"): + spec.loader = _DeferredSetupLoader(spec.loader, fullname) + return spec + + +_deferred_setup_finder = _DeferredSetupFinder() + + def _check_minimum_version( integration: "type[Integration]", version: "Optional[tuple[int, ...]]", diff --git a/tests/integrations/openai/test_openai.py b/tests/integrations/openai/test_openai.py index cf78d2dff0..dae084c95c 100644 --- a/tests/integrations/openai/test_openai.py +++ b/tests/integrations/openai/test_openai.py @@ -1,4 +1,8 @@ import json +import os +import subprocess +import sys +from textwrap import dedent import pytest @@ -8271,3 +8275,58 @@ async def test_streaming_responses_api_ttft_async( assert isinstance(ttft, float) assert ttft > 0 + + +def test_deferred_setup_on_import(tmp_path): + app = tmp_path / "app.py" + app.write_text( + dedent( + """ + import json + import sys + + import sentry_sdk + + events = [] + + def before_send(event, hint): + events.append(event) + return None + + sentry_sdk.init( + before_send=before_send, + _experiments={"deferred_auto_enabling_integrations": True}, + ) + imported_during_init = "openai" in sys.modules + + from openai.resources.chat.completions import Completions + + sentry_sdk.capture_message("hi") + + print(json.dumps({ + "imported_during_init": imported_during_init, + "integration_enabled": sentry_sdk.get_client().get_integration("openai") is not None, + "patched_by": Completions.create.__code__.co_filename, + "sdk_integrations": events[0]["sdk"]["integrations"], + })) + """ + ) + ) + + output = subprocess.check_output([sys.executable, str(app)]) + result = json.loads(output) + + assert result["imported_during_init"] is False + assert result["integration_enabled"] is True + assert result["patched_by"].endswith( + os.path.join("sentry_sdk", "integrations", "openai.py") + ) + assert "openai" in result["sdk_integrations"] + + +def test_deferred_setup_when_already_imported(sentry_init): + sentry_init(_experiments={"deferred_auto_enabling_integrations": True}) + + assert isinstance( + sentry_sdk.get_client().get_integration(OpenAIIntegration), OpenAIIntegration + ) From d46daabbf50b27da18878abb1b5f7744ec3584f9 Mon Sep 17 00:00:00 2001 From: Erica Pisani Date: Fri, 20 Nov 2026 12:53:19 -0500 Subject: [PATCH 2/2] fix(integrations): Harden deferred integration setup Leave the deferred setup finder on sys.meta_path once installed. Removing it while another thread iterates sys.meta_path can make that thread skip the next finder, and the finder returns early when nothing is pending. Treat any exception from find_spec at init as the library not being installed, and drop a pending integration whose loader has no exec_module instead of leaving it pending forever. Deferred setup now reads options from the client it registers the integration on. Refs TEL-133 --- sentry_sdk/integrations/__init__.py | 69 +++++++++++++++++------------ tests/test_basics.py | 10 +++++ 2 files changed, 50 insertions(+), 29 deletions(-) diff --git a/sentry_sdk/integrations/__init__.py b/sentry_sdk/integrations/__init__.py index 8e26a4e216..277feb2518 100644 --- a/sentry_sdk/integrations/__init__.py +++ b/sentry_sdk/integrations/__init__.py @@ -16,17 +16,23 @@ from types import ModuleType from typing import ( Any, - Callable, Dict, Iterator, List, Optional, + Protocol, Set, - Tuple, Type, Union, ) + class _DefaultIntegrationsIterator(Protocol): + def __call__( + self, + with_auto_enabling_integrations: bool, + exclude: "Container[str]" = (), + ) -> "Iterator[Type[Integration]]": ... + _DEFAULT_FAILED_REQUEST_STATUS_CODES = frozenset(range(500, 600)) @@ -39,9 +45,9 @@ # Set of all integration identifiers we have actually installed _installed_integrations: "Set[str]" = set() -# Trigger module -> (integration import string, client options) of deferred -# integrations waiting for the application to import the trigger module -_pending_deferred_integrations: "Dict[str, Tuple[str, Optional[Dict[str, Any]]]]" = {} +# Trigger module -> import string of the deferred integration waiting for the +# application to import the trigger module +_pending_deferred_integrations: "Dict[str, str]" = {} _deferred_setup_finder_guard = local() @@ -49,7 +55,7 @@ def _generate_default_integrations_iterator( integrations: "List[str]", auto_enabling_integrations: "List[str]", -) -> "Callable[..., Iterator[Type[Integration]]]": +) -> "_DefaultIntegrationsIterator": def iter_default_integrations( with_auto_enabling_integrations: bool, exclude: "Container[str]" = (), @@ -243,7 +249,10 @@ def setup_integrations( logger.debug("Setting up integrations (with default = %s)", with_defaults) - deferred: "Dict[str, Optional[str]]" = {} + # Identifier -> import string of deferred integrations whose library is installed + deferred: "Dict[str, str]" = {} + # Deferred integrations, plus those whose library isn't installed + excluded: "Set[str]" = set() if ( with_defaults and with_auto_enabling_integrations @@ -253,11 +262,15 @@ def setup_integrations( for import_string, trigger in _DEFERRED_INTEGRATION_TRIGGERS.items(): if trigger in sys.modules: continue - spec = importlib.util.find_spec(trigger) + try: + spec = importlib.util.find_spec(trigger) + except Exception: + spec = None if spec is None: - deferred[import_string] = None + excluded.add(import_string) elif hasattr(spec.loader, "exec_module"): - deferred[import_string] = trigger + excluded.add(import_string) + deferred[import_string.rsplit(".", 2)[1]] = import_string user_provided_integrations = set(integrations.keys()) @@ -272,7 +285,7 @@ def setup_integrations( if with_defaults: for integration_cls in iter_default_integrations( - with_auto_enabling_integrations, exclude=deferred + with_auto_enabling_integrations, exclude=excluded ): if integration_cls.identifier not in integrations: instance = integration_cls() @@ -292,7 +305,7 @@ def setup_integrations( for target in targets_to_deactivate: if target not in user_provided_integrations: deactivated_identifiers.add(target) - for cls in iter_default_integrations(True, exclude=deferred): + for cls in iter_default_integrations(True, exclude=excluded): if cls.identifier == target: if cls not in disabled_integrations: disabled_integrations.append(cls) @@ -326,20 +339,19 @@ def setup_integrations( _processed_integrations.add(identifier) - for import_string, trigger in deferred.items(): - identifier = import_string.rsplit(".", 2)[1] + for identifier, import_string in deferred.items(): if ( - trigger is None - or identifier in disabled_integration_identifiers + identifier in disabled_integration_identifiers or identifier in deactivated_identifiers ): continue + trigger = _DEFERRED_INTEGRATION_TRIGGERS[import_string] with _installer_lock: if identifier in _processed_integrations: continue _processed_integrations.add(identifier) - _pending_deferred_integrations[trigger] = (import_string, options) + _pending_deferred_integrations[trigger] = import_string if _deferred_setup_finder not in sys.meta_path: sys.meta_path.insert(0, _deferred_setup_finder) @@ -362,30 +374,23 @@ def setup_integrations( def _set_up_deferred_integration(trigger: str) -> None: - with _installer_lock: - pending = _pending_deferred_integrations.pop(trigger, None) - if ( - not _pending_deferred_integrations - and _deferred_setup_finder in sys.meta_path - ): - sys.meta_path.remove(_deferred_setup_finder) - - if pending is None: + import_string = _pending_deferred_integrations.pop(trigger, None) + if import_string is None: return - import_string, options = pending with capture_internal_exceptions(): + client = sentry_sdk.get_client() module, cls = import_string.rsplit(".", 1) try: integration = getattr(import_module(module), cls)() type(integration).setup_once() - integration.setup_once_with_options(options) + integration.setup_once_with_options(client.options) except DidNotEnable as e: logger.debug("Did not enable default integration %s: %s", import_string, e) return _installed_integrations.add(integration.identifier) - sentry_sdk.get_client().integrations[integration.identifier] = integration + client.integrations[integration.identifier] = integration logger.debug("Enabling integration %s", integration.identifier) @@ -435,6 +440,12 @@ def find_spec( if hasattr(spec.loader, "exec_module"): spec.loader = _DeferredSetupLoader(spec.loader, fullname) + else: + _pending_deferred_integrations.pop(fullname, None) + logger.debug( + "Not setting up deferred integration for %s: its loader has no exec_module", + fullname, + ) return spec diff --git a/tests/test_basics.py b/tests/test_basics.py index ec6612dc99..fc8110dfbb 100644 --- a/tests/test_basics.py +++ b/tests/test_basics.py @@ -112,6 +112,16 @@ def test_auto_enabling_integrations_catches_import_error(sentry_init, caplog): ), "Problem with checking auto enabling {}".format(import_string) +def test_deferred_auto_enabling_integrations_library_not_installed(sentry_init): + if importlib.util.find_spec("openai") is not None: + pytest.skip("openai is installed") + + meta_path = list(sys.meta_path) + sentry_init(_experiments={"deferred_auto_enabling_integrations": True}) + + assert sys.meta_path == meta_path + + def test_generic_mechanism(sentry_init, capture_events): sentry_init() events = capture_events()