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

Narrows the Sentry import-error suppression to only known public entrypoints of optional integration packages (via a new _OPTIONAL_INTEGRATION_ENTRYPOINT_MODULES allowlist), so that deeper internal import failures (e.g. blaxel.pydantic.custom.gemni) are still reported as potential SDK bugs.

^{Written by Mendral for commit adaf2cf.}

[mendral-app]

🧪 Testing Guide

What this PR addresses

The SDK's global sys.settrace hook reports exceptions from site-packages/blaxel to Sentry. Previously, it only suppressed opentelemetry import errors. When users don't have optional integration extras installed (e.g. blaxel[openai], blaxel[livekit]), the resulting ModuleNotFoundError was incorrectly reported to Sentry as an SDK bug. This PR expands the filter to recognize all optional integration import failures and suppress them.

Steps to reproduce the original issue

1. Install the SDK without an optional extra, e.g. pip install blaxel (no [openai] or [livekit]).
2. Attempt to import an optional integration: from blaxel.openai import model or from blaxel.livekit import model.
3. Observe that a ModuleNotFoundError is raised (expected), but prior to this fix it would also be captured and sent to Sentry as an SDK defect.

What to verify (expected behavior)

1. Unit tests pass — Run pytest tests/core/test_sentry.py and confirm all new tests are green. These cover:
   • Each optional integration package/entrypoint is recognized as optional.
   • Third-party deps missing inside an integration frame are suppressed.
   • Third-party deps missing outside integrations (e.g. in blaxel.core) are not suppressed (still reported).
   • Deeper internal blaxel.* import failures are not suppressed (still reported).
   • Chained __cause__ exceptions from friendly import guards are handled.
   • Circular __cause__ references don't cause infinite recursion.
2. Existing Sentry behavior preserved — opentelemetry import errors are still suppressed (covered by test).
3. No regression in real error reporting — A genuine SDK packaging bug (e.g. ModuleNotFoundError: No module named 'blaxel.core.missing') should still be captured and forwarded to Sentry.
4. Cross-platform path detection — The _OPTIONAL_INTEGRATION_PATHS tuple includes both / and \ separators for POSIX and Windows.

Note

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

[mendral-app]

🔀 Interaction Flow Diagram

Here's a sequence diagram showing how the updated Sentry error filtering pipeline processes import errors after this PR:

sequenceDiagram
    participant User as User Code
    participant Init as blaxel.{integration}/__init__.py
    participant Hook as sys.settrace Hook
    participant Filter as _is_optional_dependency_error()
    participant L1 as Level 1: Entrypoint Check
    participant L2 as Level 2: 3rd-party Deps
    participant L3 as Level 3: __cause__ Chain
    participant L4 as Level 4: Integration Frame
    participant Sentry as Sentry

    User->>Init: import blaxel.openai
    Init->>Init: from .model import * (missing extra)
    Init-->>Hook: ModuleNotFoundError raised
    Hook->>Filter: _is_optional_dependency_error(exc)

    Filter->>L1: _is_optional_integration_entrypoint_missing()
    Note right of L1: Check module name against<br/>_OPTIONAL_INTEGRATION_PACKAGES<br/>& _ENTRYPOINT_MODULES

    alt Module is known optional entrypoint
        L1-->>Filter: True
        Filter-->>Hook: Suppress (not reported)
    else Not a direct entrypoint
        Filter->>L2: Check _OPTIONAL_DEPENDENCIES list
        alt Known optional dep (e.g. opentelemetry)
            L2-->>Filter: True
            Filter-->>Hook: Suppress
        else Unknown dependency
            Filter->>L3: Walk exc.__cause__ chain (cycle-safe)
            alt Wrapped ImportError from integration guard
                L3-->>Filter: True
                Filter-->>Hook: Suppress
            else No matching cause
                Filter->>L4: _has_optional_integration_frame()
                Note right of L4: Walk traceback for<br/>integration directory paths
                alt 3rd-party import inside integration frame
                    L4-->>Filter: True
                    Filter-->>Hook: Suppress
                else Core SDK or unknown origin
                    L4-->>Filter: False
                    Filter-->>Hook: Report as SDK bug
                    Hook->>Sentry: Send event
                end
            end
        end
    end

Loading

Summary

This PR introduces a 4-level hierarchical filter in the Sentry error hook to prevent optional-integration ModuleNotFoundErrors from being reported as SDK bugs:

Level	What it catches	Example
1	Direct missing integration entrypoints	blaxel.openai.model, blaxel.livekit.model
2	Known optional third-party deps	opentelemetry (existing behavior)
3	Wrapped errors via __cause__ chain	Integration guard code re-raising
4	Non-blaxel imports inside integration frames	Missing agents pkg during blaxel.openai load

Genuine SDK bugs (e.g., core blaxel.* modules failing to import) still flow through to Sentry. The new test suite covers all paths including cycle detection for self-referencing __cause__ chains.

Note

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

[mendral-app]

LGTM

The refinement from broad startswith matching to an explicit entrypoint allowlist is a good tightening of the filter. Logic is correct, cycle detection is preserved, and the new test (test_missing_nested_blaxel_module_inside_integration_is_not_optional) validates the key behavioral change. No new correctness or security concerns.

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