TASK-028: Add exception logging to fire-and-forget asyncio.create_task()

- Create logged_task() helper in backend/app/utils/async_utils.py to wrap
  fire-and-forget coroutines with exception logging
- Ensures unhandled task exceptions are always logged to structlog instead of
  silently discarded (Python 3.11+ RuntimeWarning)
- Update ban_service.py to use logged_task() for geo_cache.lookup_batch()
  background resolution
- Add comprehensive tests for logged_task() in test_async_utils.py
- Document fire-and-forget task conventions in Backend-Development.md

The logged_task() wrapper catches any exception raised in a background task,
logs it with full traceback context and task name, and never re-raises.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
2026-04-26 15:17:30 +02:00
parent 46fa7c78bc
commit 5d24780c63
5 changed files with 158 additions and 37 deletions

View File

@@ -309,6 +309,59 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
await app.state.db.close()
```
### Fire-and-Forget Background Tasks
When you need to spawn a background task that runs independently without waiting for the result, use `asyncio.create_task()` with the `logged_task()` helper from `app.utils.async_utils`. This ensures exceptions in background tasks are always logged and never silently discarded.
**Why this matters:** In Python 3.11+, unhandled exceptions in fire-and-forget tasks become silent `RuntimeWarning`s. Without logging, background errors (network failures, database writes, API timeouts) become invisible in structured logs and are extremely hard to debug.
**Pattern:**
```python
from app.utils.async_utils import logged_task
# Bad — exceptions are silently discarded
asyncio.create_task(some_background_work())
# Good — exceptions are logged
asyncio.create_task(
logged_task(some_background_work(), "task_name"),
name="task_name",
)
```
The `logged_task()` wrapper:
- Wraps your coroutine to catch any exception
- Logs the exception with `log.exception()` (structlog automatically captures the traceback)
- Adds `task_name` to the structured log context
- Never re-raises — it's safe to use with `asyncio.create_task()`
Example:
```python
import asyncio
from app.utils.async_utils import logged_task
import structlog
log = structlog.get_logger()
async def geo_lookup_batch(ips: list[str]) -> None:
"""Look up geolocation data for IPs asynchronously."""
try:
for ip in ips:
# May timeout, fail network call, or fail DB write
location = await lookup_ip_location(ip)
await db.execute(INSERT_GEO_SQL, (ip, location))
await db.commit()
except Exception:
# All exceptions are automatically logged by logged_task() wrapper
raise
# In your request handler or service:
asyncio.create_task(
logged_task(geo_lookup_batch(uncached_ips), "geo_cache_batch"),
name="geo_cache_batch",
)
```
---
## 6.1 Database Query Conventions