fix(sentry): stop reporting optional-integration import errors as SDK bugs

[cursor]

Problem

Sentry issue SDK-PYTHON-YY — ModuleNotFoundError: No module named 'blaxel.livekit.model' (clustered with No module named 'blaxel.openai.model'), 7 occurrences, 0 users impacted, release sdk-python@0.2.58.

Root cause

The SDK installs a global sys.settrace hook (src/blaxel/core/common/sentry.py) that forwards any exception whose frame lives in site-packages/blaxel to Blaxel's Sentry. Its _is_optional_dependency_error allow-list only knew about opentelemetry.

When a user imports an optional framework integration (blaxel.openai, blaxel.livekit, …) in an environment that is missing the matching extra — or runs a stripped/partial install where the integration's model.py is absent (common in .pyenv-based agent images, which is the exact production case: culprit blaxel/<pkg>/__init__.py line 3 = from .model import *) — the resulting ModuleNotFoundError was captured and reported as if it were an SDK defect. These are environment issues, not SDK bugs.

I verified this empirically:

• The published 0.2.58 wheel and sdist both contain model.py for every integration (so it is not a packaging bug).
• Removing blaxel/openai/model.py from a clean install reproduces the exact Sentry signature, including exc.name == 'blaxel.openai.model' and the single __init__.py line-3 frame.

Fix

Expand _is_optional_dependency_error to also treat as expected (and therefore not report):

• import errors for any optional blaxel integration subpackage (blaxel.langgraph, blaxel.llamaindex, blaxel.openai, blaxel.crewai, blaxel.googleadk, blaxel.livekit, blaxel.pydantic, blaxel.telemetry), and
• import failures of non-blaxel third-party deps raised while loading one of those integration packages (e.g. agents, livekit).

Genuine SDK import bugs (failures on blaxel.* core modules) are still captured.

Validation

• New unit tests in tests/core/test_sentry.py (8 cases) — all pass.
• End-to-end: feeding the exact production exception through the trace hook is now suppressed, while a simulated genuine core bug (blaxel.core.broken) is still captured.
• Existing unit suite: 281 passing (3 unrelated pre-existing failures require BL_API_KEY credentials not present in CI sandbox). ruff check + ruff format clean.

Remaining risk

Low. The change only narrows what is sent to Sentry, scoped to ImportError from optional integration packages; it does not alter integration behavior or what users see at import time.

Fixes SDK-PYTHON-YY

  

---

Note

Expands the Sentry error filter to suppress ImportError/ModuleNotFoundError exceptions from optional integration packages (e.g. blaxel.openai, blaxel.livekit) so they are not reported as SDK bugs. Adds a traceback-walking heuristic for third-party deps failing inside integration code, and covers the logic with unit tests.

^{Written by Mendral for commit cb2dc73.}

[mendral-app]

🧪 Testing Guide

What this PR addresses

The SDK's global sys.settrace hook reports exceptions originating from blaxel code to Sentry. However, when users import optional integration packages (e.g. blaxel.openai, blaxel.livekit) without installing the corresponding extras, the resulting ModuleNotFoundError is incorrectly reported to Sentry as an SDK bug. This PR expands the _is_optional_dependency_error filter to suppress these expected environment errors for all optional integration subpackages.

Steps to reproduce the original issue

1. Install the blaxel SDK without an optional extra (e.g. do NOT install blaxel[openai] or blaxel[livekit]).
2. Ensure Sentry reporting is enabled (the default in production environments).
3. Trigger code that attempts to import an optional integration, e.g. from blaxel.openai.model import * or from blaxel.livekit.model import *.
4. Observe that a ModuleNotFoundError event is sent to Sentry (visible in the SDK-PYTHON-YY issue).

What to verify (expected behavior)

1. New tests pass: Run pytest tests/core/test_sentry.py -v — all 8 test cases should pass, covering:
   • Missing integration submodules (e.g. blaxel.openai.model) are classified as optional ✓
   • Missing third-party deps imported within an integration path (e.g. agents inside blaxel/openai/) are classified as optional ✓
   • Missing third-party deps outside integration paths (e.g. httpx in blaxel/core/) are still reported ✓
   • Core SDK module errors (blaxel.core.missing) are still reported ✓
   • Non-ImportError exceptions are not affected ✓
2. Existing tests still pass: Run the full test suite to check for regressions.
3. Logic review: Verify that the _OPTIONAL_INTEGRATION_PACKAGES tuple covers all known optional integrations and that the path-matching logic handles both POSIX (/) and Windows (\) separators.
4. No over-suppression: Confirm that a genuine ImportError from a core SDK module (e.g. blaxel.core.common.settings) would NOT be filtered out — the test test_core_module_import_error_is_not_optional validates this.

Note

Posted by PR Testing Guide · Tag @mendral-app with feedback.

[mendral-app]

LGTM

The logic is sound: the three checks correctly classify integration import errors as expected while preserving reporting for core module failures. The traceback walk is bounded (no infinite loop risk), the if missing guard prevents the empty-string edge case, and the not missing.startswith("blaxel") condition ensures genuine SDK import bugs on blaxel.* core modules still reach Sentry. The hardcoded _OPTIONAL_INTEGRATION_PACKAGES list will require manual updates when new integrations are added, but that's an acceptable maintenance trade-off for explicit control over the filter scope. Tests are well-structured and cover the key cases.

_{Tag @mendral-app with feedback or questions. View session}

[mendral-app]

🔀 Interaction Flow

This PR enhances the Sentry error filtering in the SDK to suppress optional-integration ImportErrors from being reported as bugs. Here's the sequence of interactions:

sequenceDiagram
    participant App as User Application
    participant Hook as sys.settrace Hook
    participant Filter as _is_optional_dependency_error()
    participant Pkgs as _OPTIONAL_INTEGRATION_PACKAGES
    participant Paths as _OPTIONAL_INTEGRATION_PATHS
    participant Sentry as Sentry (Remote)

    App->>Hook: ImportError raised in blaxel frame
    Hook->>Filter: exc_type, exc_value

    alt Not an ImportError
        Filter-->>Hook: False (report it)
        Hook->>Sentry: Forward exception
    else Tier 1: Missing module matches optional package
        Filter->>Pkgs: Check exc_value.name against package list
        Pkgs-->>Filter: Match found (e.g. blaxel.openai.model)
        Filter-->>Hook: True (suppress)
    else Tier 2: Known optional third-party dep (e.g. opentelemetry)
        Filter-->>Hook: True (suppress)
    else Tier 3: Non-blaxel import failing inside integration path
        Filter->>Paths: Walk traceback, check frame paths
        Paths-->>Filter: Frame in optional integration directory
        Filter-->>Hook: True (suppress)
    else No match in any tier
        Filter-->>Hook: False (report it)
        Hook->>Sentry: Forward exception
    end

Loading

Summary

The refactored _is_optional_dependency_error() now uses a three-tier classification to decide if an ImportError is noise from a missing optional integration or a genuine SDK bug:

Tier	Check	Example
1	Missing module name ∈ optional packages	blaxel.livekit.model
2	Error mentions known optional deps	opentelemetry
3	Traceback frame lives in an integration path	Third-party dep missing while loading blaxel.openai

Only errors that fail all three tiers are forwarded to Sentry, ensuring real SDK bugs still get reported.

Note

Posted by PR Sequence Diagram · Tag @mendral-app with feedback.