fix: Selective disabling option for N+1 warnings

docs/performance/allow_n_plus_one.rst

@@ -0,0 +1,22 @@
+Mark expected N+1 loops
+======================
+
+The SDK provides a small helper to mark transactions or spans where an N+1 loop is
+expected and acceptable.
+
+.. code-block:: python
+
+    from sentry_sdk.performance import allow_n_plus_one
+
+    with sentry_sdk.start_transaction(name="process_items"):
+        with allow_n_plus_one("expected batch processing"):
+            for item in items:
+                process(item)
+
+Notes
+-----
+
+- This helper sets the tag ``sentry.n_plus_one.ignore`` (and optional
+  ``sentry.n_plus_one.reason``) on the current transaction and current span.
+- Server-side support is required for the N+1 detector to actually ignore
+  transactions with this tag. The SDK only attaches the metadata.

sentry_sdk/__init__.py

@@ -55,6 +55,10 @@
     "update_current_span",
 ]
 
+# Public convenience submodule for performance helpers
+from sentry_sdk import performance as performance
+__all__.append("performance")
+
 # Initialize the debug support after everything is loaded
 from sentry_sdk.debug import init_debug_support
 

sentry_sdk/performance.py

@@ -0,0 +1,33 @@
+from contextlib import contextmanager
+import sentry_sdk
+
+
+@contextmanager
+def allow_n_plus_one(reason=None):
+    """Context manager to mark the current transaction/spans as allowed N+1.
+
+    This sets a tag on the current transaction and current span so the server
+    side N+1 detector can (optionally) ignore this transaction. The server
+    change is required for ignoring to take effect; this helper simply
+    attaches metadata to the event.
+
+    Usage:
+        with allow_n_plus_one("expected loop"):
+            for x in queryset:
+                ...
+    """
+    tx = sentry_sdk.get_current_span()
+    if tx is not None:
+        try:
+            tx.set_tag("sentry.n_plus_one.ignore", True)
+            if reason:
+                tx.set_tag("sentry.n_plus_one.reason", reason)
+        except Exception:
+            # best-effort
+            pass
+
+    try:
+        yield
+    finally:
+        # leave the tag in place so the transaction contains it when sent
+        pass

tests/tracing/test_allow_n_plus_one.py

@@ -0,0 +1,16 @@
+import sentry_sdk
+from sentry_sdk.performance import allow_n_plus_one
+
+
+def test_allow_n_plus_one_sets_tag(sentry_init):
+    # Initialize SDK with test fixture
+    sentry_init()
+
+    with sentry_sdk.start_transaction(name="tx") as tx:
+        with allow_n_plus_one("expected"):
+            # no-op loop simulated
+            pass
+
+        # The tag should be set on the transaction
+        assert tx._tags.get("sentry.n_plus_one.ignore") is True
+        assert tx._tags.get("sentry.n_plus_one.reason") == "expected"