ref: Unify warnings (warnings.warn for deprecations, logging.warning for everything else)

MIGRATION_GUIDE.md

@@ -24,6 +24,7 @@ Looking to upgrade from Sentry SDK 2.x to 3.x? Here's a comprehensive list of wh
 - The UnraisableHookIntegration is now enabled by default.
 - We now don't suppress chained exceptions in the ASGI and asyncio integrations by default. The related `suppress_asgi_chained_exceptions` experimental option was removed.
 - In the AWS Lambda and GCP integrations, the message of the warning the SDK optionally emits if a function is about to time out has changed.
+- We changed the way we emit warnings. Deprecations will from now on be always emitted using `warnings.warn()`, while all other warnings will be emitted using `logger.warning()`.
 - `sentry_sdk.init()` can no longer be used as a context manager.
 
 ### Logging

sentry_sdk/_compat.py

@@ -61,30 +61,26 @@ def enabled(option: str) -> bool:
     lazy_mode = enabled("lazy-apps") or enabled("lazy")
 
     if lazy_mode and not threads_enabled:
-        from warnings import warn
-
-        warn(
-            Warning(
-                "IMPORTANT: "
-                "We detected the use of uWSGI without thread support. "
-                "This might lead to unexpected issues. "
-                'Please run uWSGI with "--enable-threads" for full support.'
-            )
+        from sentry_sdk.utils import logger
+
+        logger.warning(
+            "IMPORTANT: "
+            "We detected the use of uWSGI without thread support. "
+            "This might lead to unexpected issues. "
+            'Please run uWSGI with "--enable-threads" for full support.'
         )
 
         return False
 
     elif not lazy_mode and (not threads_enabled or not fork_hooks_on):
-        from warnings import warn
-
-        warn(
-            Warning(
-                "IMPORTANT: "
-                "We detected the use of uWSGI in preforking mode without "
-                "thread support. This might lead to crashing workers. "
-                'Please run uWSGI with both "--enable-threads" and '
-                '"--py-call-uwsgi-fork-hooks" for full support.'
-            )
+        from sentry_sdk.utils import logger
+
+        logger.warning(
+            "IMPORTANT: "
+            "We detected the use of uWSGI in preforking mode without "
+            "thread support. This might lead to crashing workers. "
+            'Please run uWSGI with both "--enable-threads" and '
+            '"--py-call-uwsgi-fork-hooks" for full support.'
         )
 
         return False

sentry_sdk/client.py

@@ -5,7 +5,6 @@
 import socket
 import sys
 import uuid
-import warnings
 from collections.abc import Iterable, Mapping
 from contextvars import ContextVar
 from datetime import datetime, timezone
@@ -348,9 +347,8 @@ def _get_options(*args: "Optional[str]", **kwargs: "Any") -> "Dict[str, Any]":
             else rv["send_default_pii"]
         )
     elif has_data_collection_enabled(rv) and rv["event_scrubber"]:
-        warnings.warn(
+        logger.warning(
             "Event scrubbers are not enabled when data collection configuration is provided. Ignoring event_scrubber...",
-            stacklevel=2,
         )
         rv["event_scrubber"] = None
 
@@ -366,21 +364,18 @@ def _get_options(*args: "Optional[str]", **kwargs: "Any") -> "Dict[str, Any]":
         )
 
     if rv["trace_ignore_status_codes"] and has_span_streaming_enabled(rv):
-        warnings.warn(
+        logger.warning(
             "The `trace_ignore_status_codes` parameter is ignored in span streaming mode.",
-            stacklevel=2,
         )
 
     if rv["ignore_spans"] and not has_span_streaming_enabled(rv):
-        warnings.warn(
+        logger.warning(
             "The `ignore_spans` parameter only works when `trace_lifecycle` is set to `stream`.",
-            stacklevel=2,
         )
 
     if rv["before_send_span"] and not has_span_streaming_enabled(rv):
-        warnings.warn(
+        logger.warning(
             "The `before_send_span` parameter only works when `trace_lifecycle` is set to `stream`.",
-            stacklevel=2,
         )
 
     return rv
@@ -1334,9 +1329,8 @@ def close(
         """
         if self.transport is not None:
             if self._has_async_transport():
-                warnings.warn(
+                logger.warning(
                     "close() used with AsyncHttpTransport. Use close_async() instead.",
-                    stacklevel=2,
                 )
                 self._flush_components()
             else:
@@ -1381,9 +1375,8 @@ def flush(
         """
         if self.transport is not None:
             if self._has_async_transport():
-                warnings.warn(
+                logger.warning(
                     "flush() used with AsyncHttpTransport. Use flush_async() instead.",
-                    stacklevel=2,
                 )
                 return
             if timeout is None:

sentry_sdk/data_collection.py

@@ -22,11 +22,11 @@
   ``DeprecationWarning`` is emitted for ``send_default_pii``.
 """
 
-import warnings
 from typing import TYPE_CHECKING, List, Mapping, Optional, Union, cast
 from urllib.parse import parse_qs, urlencode
 
 from sentry_sdk._types import SENSITIVE_DATA_SUBSTITUTE
+from sentry_sdk.utils import deprecation_warning
 
 if TYPE_CHECKING:
     from typing import Any, Dict
@@ -315,11 +315,9 @@ def _resolve_data_collection(options: "Dict[str, Any]") -> "DataCollection":
                 )
             )
         if send_default_pii is not None:
-            warnings.warn(
+            deprecation_warning(
                 "`send_default_pii` is deprecated and ignored when "
                 "`data_collection` is set.",
-                DeprecationWarning,
-                stacklevel=2,
             )
         return _resolve_explicit(
             user_dc,

sentry_sdk/integrations/sanic.py

@@ -1,5 +1,4 @@
 import sys
-import warnings
 import weakref
 from inspect import isawaitable
 from typing import TYPE_CHECKING
@@ -22,6 +21,7 @@
     ensure_integration_enabled,
     event_from_exception,
     has_data_collection_enabled,
+    logger,
     parse_version,
     reraise,
 )
@@ -155,9 +155,8 @@ async def _context_enter(request: "Request") -> None:
             isinstance(integration, SanicIntegration)
             and integration._unsampled_statuses
         ):
-            warnings.warn(
+            logger.warning(
                 "The `unsampled_statuses` option of SanicIntegration has no effect when span streaming is enabled.",
-                stacklevel=2,
             )
 
         sentry_sdk.traces.continue_trace(dict(request.headers))

sentry_sdk/integrations/strawberry.py

@@ -1,5 +1,4 @@
 import functools
-import warnings
 from inspect import isawaitable
 
 import sentry_sdk
@@ -13,6 +12,7 @@
     ensure_integration_enabled,
     event_from_exception,
     has_data_collection_enabled,
+    logger,
     package_version,
 )
 
@@ -95,9 +95,8 @@ def _sentry_patched_schema_init(
             should_use_async_extension = _guess_if_using_async(extensions)
 
             if should_use_async_extension is None:
-                warnings.warn(
+                logger.warning(
                     "Assuming strawberry is running sync. If not, initialize the integration as StrawberryIntegration(async_execution=True).",
-                    stacklevel=2,
                 )
                 should_use_async_extension = False
 

sentry_sdk/integrations/threading.py

@@ -1,5 +1,4 @@
 import sys
-import warnings
 from concurrent.futures import Future, ThreadPoolExecutor
 from functools import wraps
 from threading import Thread, current_thread
@@ -11,6 +10,7 @@
 from sentry_sdk.utils import (
     capture_internal_exceptions,
     event_from_exception,
+    logger,
     reraise,
 )
 
@@ -62,12 +62,11 @@ def sentry_start(self: "Thread", *a: "Any", **kw: "Any") -> "Any":
 
             if integration.propagate_scope:
                 if is_async_emulated_with_threads:
-                    warnings.warn(
+                    logger.warning(
                         "There is a known issue with Django channels 2.x and 3.x when using Python 3.8 or older. "
                         "(Async support is emulated using threads and some Sentry data may be leaked between those threads.) "
                         "Please either upgrade to Django channels 4.0+, use Django's async features "
                         "available in Django 3.1+ instead of Django channels, or upgrade to Python 3.9+.",
-                        stacklevel=2,
                     )
                     isolation_scope = sentry_sdk.get_isolation_scope()
                     current_scope = sentry_sdk.get_current_scope()

sentry_sdk/scope.py

@@ -1,7 +1,6 @@
 import os
 import platform
 import sys
-import warnings
 from collections import deque
 from contextlib import contextmanager
 from contextvars import ContextVar
@@ -51,6 +50,7 @@
     capture_internal_exception,
     capture_internal_exceptions,
     datetime_from_isoformat,
+    deprecation_warning,
     disable_capture_event,
     event_from_exception,
     exc_info_from_error,
@@ -755,10 +755,8 @@ def transaction(self) -> "Any":
             return None
 
         if isinstance(self._span, StreamedSpan):
-            warnings.warn(
+            deprecation_warning(
                 "Scope.transaction is not available in streaming mode.",
-                DeprecationWarning,
-                stacklevel=2,
             )
             return None
 
@@ -793,10 +791,8 @@ def transaction(self, value: "Any") -> None:
         self._transaction = value
         if self._span:
             if isinstance(self._span, StreamedSpan):
-                warnings.warn(
+                deprecation_warning(
                     "Scope.transaction is not available in streaming mode.",
-                    DeprecationWarning,
-                    stacklevel=2,
                 )
                 return None
 
@@ -1078,10 +1074,8 @@ def start_transaction(
         """
         client = self.get_client()
         if has_span_streaming_enabled(client.options):
-            warnings.warn(
+            deprecation_warning(
                 "Scope.start_transaction is not available in streaming mode.",
-                DeprecationWarning,
-                stacklevel=2,
             )
             return NoOpSpan()
 
@@ -1155,18 +1149,14 @@ def start_span(self, **kwargs: "Any") -> "Span":
         """
         client = sentry_sdk.get_client()
         if has_span_streaming_enabled(client.options):
-            warnings.warn(
+            deprecation_warning(
                 "Scope.start_span is not available in streaming mode.",
-                DeprecationWarning,
-                stacklevel=2,
             )
             return NoOpSpan()
 
         if kwargs.get("description") is not None:
-            warnings.warn(
+            deprecation_warning(
                 "The `description` parameter is deprecated. Please use `name` instead.",
-                DeprecationWarning,
-                stacklevel=2,
             )
 
         with new_scope():

sentry_sdk/traces.py

@@ -9,7 +9,6 @@
 
 import sys
 import uuid
-import warnings
 from datetime import datetime, timedelta, timezone
 from enum import Enum
 from typing import TYPE_CHECKING
@@ -24,6 +23,7 @@
 from sentry_sdk.tracing_utils import Baggage
 from sentry_sdk.utils import (
     capture_internal_exceptions,
+    deprecation_warning,
     format_attribute,
     get_current_thread_meta,
     logger,
@@ -170,11 +170,10 @@ def start_span(
 
     client = sentry_sdk.get_client()
     if client.is_active() and not has_span_streaming_enabled(client.options):
-        warnings.warn(
+        logger.warning(
             "Using span streaming API in non-span-streaming mode. Use "
             "sentry_sdk.start_transaction() and sentry_sdk.start_span() "
             "instead.",
-            stacklevel=2,
         )
         return NoOpStreamedSpan()
 
@@ -349,10 +348,8 @@ def end(self, end_timestamp: "Optional[Union[float, datetime]]" = None) -> None:
         self._end(end_timestamp)
 
     def finish(self, end_timestamp: "Optional[Union[float, datetime]]" = None) -> None:
-        warnings.warn(
+        deprecation_warning(
             "span.finish() is deprecated. Use span.end() instead.",
-            stacklevel=2,
-            category=DeprecationWarning,
         )
 
         self.end(end_timestamp)
@@ -718,10 +715,8 @@ def end(self, end_timestamp: "Optional[Union[float, datetime]]" = None) -> None:
         self._end()
 
     def finish(self, end_timestamp: "Optional[Union[float, datetime]]" = None) -> None:
-        warnings.warn(
+        deprecation_warning(
             "span.finish() is deprecated. Use span.end() instead.",
-            stacklevel=2,
-            category=DeprecationWarning,
         )
 
         self._end()

sentry_sdk/tracing.py

@@ -1,5 +1,4 @@
 import uuid
-import warnings
 from datetime import datetime, timedelta, timezone
 from enum import Enum
 from typing import TYPE_CHECKING, cast
@@ -9,6 +8,7 @@
 from sentry_sdk.profiler.continuous_profiler import get_profiler_id
 from sentry_sdk.utils import (
     capture_internal_exceptions,
+    deprecation_warning,
     get_current_thread_meta,
     is_valid_sample_rate,
     logger,
@@ -417,10 +417,8 @@ def start_child(self, **kwargs: "Any") -> "Span":
         inherited from the current span/transaction.
         """
         if kwargs.get("description") is not None:
-            warnings.warn(
+            deprecation_warning(
                 "The `description` parameter is deprecated. Please use `name` instead.",
-                DeprecationWarning,
-                stacklevel=2,
             )
 
         kwargs.setdefault("sampled", self.sampled)