Improve asyncio integration error handling. (#4129)

Instrumenting asyncio projects can be confusing. Here are two
improvements:

- If users try to init the Sentry SDK outside of an async loop, a
warning message will now printed instructing them how to correctly call
init() in async envrionments. Including a link to the docs.

- During shutdown of Python unfinished async tasks emit an error `Task
was destroyed but it is pending!`. This happens if you use Sentry or
not. The error message is confusing and led people to believe the Sentry
instrumentation caused this problem. This is now remediated by
- The tasks is wrapped by Sentry, but we now **set the name of the
wrapped task to include the original** and (and a hint that is has been
wrapped by Sentry) to show that the original task is failing, not just
some Sentry task unknown to the user.
- When shutting down a **info message** is printed, informing that there
could be `Task was destroyed but it is pending!` but that those are OK
and not a problem with the users code or Sentry.


Before this PR the users saw this during shutdown:

```
Exception ignored in: <coroutine object patch_asyncio.<locals>._sentry_task_factory.<locals>._coro_creating_hub_and_span at 0x103ae84f0>
Traceback (most recent call last):
  File "/Users/antonpirker/code/sentry-python/sentry_sdk/integrations/asyncio.py", line 46, in _coro_creating_hub_and_span
    with sentry_sdk.isolation_scope():
  File "/Users/antonpirker/.pyenv/versions/3.12.3/lib/python3.12/contextlib.py", line 158, in __exit__
    self.gen.throw(value)
  File "/Users/antonpirker/code/sentry-python/sentry_sdk/scope.py", line 1732, in isolation_scope
    _current_scope.reset(current_token)
ValueError: <Token var=<ContextVar name='current_scope' default=None at 0x102a87f60> at 0x103b1cfc0> was created in a different Context
Task was destroyed but it is pending!
task: <Task cancelling name='Task-2' coro=<patch_asyncio.<locals>._sentry_task_factory.<locals>._coro_creating_hub_and_span() done, defined at /Users/antonpirker/code/sentry-python/sentry_sdk/integrations/asyncio.py:42> wait_for=<Future pending cb=[Task.task_wakeup()]> cb=[gather.<locals>._done_callback() at /Users/antonpirker/.pyenv/versions/3.12.3/lib/python3.12/asyncio/tasks.py:767]>
```

With this PR the users will see this during shutdown:
Note the INFO message on top and also the task name on the bottom.
```
[sentry] INFO: AsyncIO is shutting down. If you see 'Task was destroyed but it is pending!' errors with '_task_with_sentry_span_creation', these are normal during shutdown and not a problem with your code or Sentry.
Exception ignored in: <coroutine object patch_asyncio.<locals>._sentry_task_factory.<locals>._task_with_sentry_span_creation at 0x1028fc4f0>
Traceback (most recent call last):
  File "/Users/antonpirker/code/sentry-python/sentry_sdk/integrations/asyncio.py", line 62, in _task_with_sentry_span_creation
    with sentry_sdk.isolation_scope():
  File "/Users/antonpirker/.pyenv/versions/3.12.3/lib/python3.12/contextlib.py", line 158, in __exit__
    self.gen.throw(value)
  File "/Users/antonpirker/code/sentry-python/sentry_sdk/scope.py", line 1732, in isolation_scope
    _current_scope.reset(current_token)
ValueError: <Token var=<ContextVar name='current_scope' default=None at 0x10193ff10> at 0x1029710c0> was created in a different Context
Task was destroyed but it is pending!
task: <Task cancelling name='long_running_task (Sentry-wrapped)' coro=<patch_asyncio.<locals>._sentry_task_factory.<locals>._task_with_sentry_span_creation() done, defined at /Users/antonpirker/code/sentry-python/sentry_sdk/integrations/asyncio.py:58> wait_for=<Future pending cb=[Task.task_wakeup()]> cb=[gather.<locals>._done_callback() at /Users/antonpirker/.pyenv/versions/3.12.3/lib/python3.12/asyncio/tasks.py:767]>
```

Fixes #2908

Improves #2333

Author: antonpirker

Diff for: sentry_sdk/integrations/asyncio.py

@@ -1,17 +1,18 @@
 import sys
+import signal
 
 import sentry_sdk
 from sentry_sdk.consts import OP
 from sentry_sdk.integrations import Integration, DidNotEnable
-from sentry_sdk.utils import event_from_exception, reraise
+from sentry_sdk.utils import event_from_exception, logger, reraise
 
 try:
     import asyncio
     from asyncio.tasks import Task
 except ImportError:
     raise DidNotEnable("asyncio not available")
 
-from typing import TYPE_CHECKING
+from typing import cast, TYPE_CHECKING
 
 if TYPE_CHECKING:
     from typing import Any
@@ -36,10 +37,26 @@ def patch_asyncio():
         loop = asyncio.get_running_loop()
         orig_task_factory = loop.get_task_factory()
 
+        # Add a shutdown handler to log a helpful message
+        def shutdown_handler():
+            # type: () -> None
+            logger.info(
+                "AsyncIO is shutting down. If you see 'Task was destroyed but it is pending!' "
+                "errors with '_task_with_sentry_span_creation', these are normal during shutdown "
+                "and not a problem with your code or Sentry."
+            )
+
+        try:
+            loop.add_signal_handler(signal.SIGINT, shutdown_handler)
+            loop.add_signal_handler(signal.SIGTERM, shutdown_handler)
+        except (NotImplementedError, AttributeError):
+            # Signal handlers might not be supported on all platforms
+            pass
+
         def _sentry_task_factory(loop, coro, **kwargs):
             # type: (asyncio.AbstractEventLoop, Coroutine[Any, Any, Any], Any) -> asyncio.Future[Any]
 
-            async def _coro_creating_hub_and_span():
+            async def _task_with_sentry_span_creation():
                 # type: () -> Any
                 result = None
 
@@ -56,27 +73,47 @@ async def _coro_creating_hub_and_span():
 
                 return result
 
+            task = None
+
             # Trying to use user set task factory (if there is one)
             if orig_task_factory:
-                return orig_task_factory(loop, _coro_creating_hub_and_span(), **kwargs)
-
-            # The default task factory in `asyncio` does not have its own function
-            # but is just a couple of lines in `asyncio.base_events.create_task()`
-            # Those lines are copied here.
-
-            # WARNING:
-            # If the default behavior of the task creation in asyncio changes,
-            # this will break!
-            task = Task(_coro_creating_hub_and_span(), loop=loop, **kwargs)
-            if task._source_traceback:  # type: ignore
-                del task._source_traceback[-1]  # type: ignore
+                task = orig_task_factory(
+                    loop, _task_with_sentry_span_creation(), **kwargs
+                )
+
+            if task is None:
+                # The default task factory in `asyncio` does not have its own function
+                # but is just a couple of lines in `asyncio.base_events.create_task()`
+                # Those lines are copied here.
+
+                # WARNING:
+                # If the default behavior of the task creation in asyncio changes,
+                # this will break!
+                task = Task(_task_with_sentry_span_creation(), loop=loop, **kwargs)
+                if task._source_traceback:  # type: ignore
+                    del task._source_traceback[-1]  # type: ignore
+
+            # Set the task name to include the original coroutine's name
+            try:
+                cast("asyncio.Task[Any]", task).set_name(
+                    f"{get_name(coro)} (Sentry-wrapped)"
+                )
+            except AttributeError:
+                # set_name might not be available in all Python versions
+                pass
 
             return task
 
         loop.set_task_factory(_sentry_task_factory)  # type: ignore
+
     except RuntimeError:
         # When there is no running loop, we have nothing to patch.
-        pass
+        logger.warning(
+            "There is no running asyncio loop so there is nothing Sentry can patch. "
+            "Please make sure you call sentry_sdk.init() within a running "
+            "asyncio loop for the AsyncioIntegration to work. "
+            "See https://docs.sentry.io/platforms/python/integrations/asyncio/"
+        )
 
 
 def _capture_exception():