Update observability docs and task utilities

- Add Observability.md documentation
- Standardize task logging with correlation_id support
- Add log_sanitizer utility for PII masking
- Update Tasks.md tracking
- Update geo_cache tasks and other task modules with correlation_id

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
2026-05-03 11:52:09 +02:00
parent 7b93499551
commit 0133489920
17 changed files with 582 additions and 124 deletions

View File

@@ -13,16 +13,21 @@ The task runs every 10 minutes. On each invocation it:
3. Delegates to :meth:`~app.services.geo_cache.GeoCache.lookup_batch` which
already handles rate-limit throttling and retries.
4. Logs how many IPs were retried and how many resolved successfully.
Correlation IDs are propagated through the task using :mod:`app.utils.correlation`
so that task logs can be correlated across runs.
"""
from __future__ import annotations
import uuid
from typing import TYPE_CHECKING
import structlog
from app.tasks.db import task_db
from app.tasks.timeout_utils import run_with_timeout
from app.utils.correlation import get_correlation_id, reset_correlation_id, set_correlation_id
from app.utils.runtime_state import get_effective_settings
if TYPE_CHECKING:
@@ -45,7 +50,10 @@ TASK_TIMEOUT_SECONDS: int = 120
async def _run_re_resolve_with_resources(
geo_cache: GeoCache, settings: Settings, http_session: ClientSession
geo_cache: GeoCache,
settings: Settings,
http_session: ClientSession,
correlation_id: str | None = None,
) -> None:
"""Query NULL-country IPs from the database and re-resolve them.
@@ -53,7 +61,24 @@ async def _run_re_resolve_with_resources(
geo_cache: The application's GeoCache instance.
settings: The resolved application settings used for database access.
http_session: The shared aiohttp session used for external lookups.
correlation_id: Optional correlation ID for log correlation.
"""
if correlation_id is None:
correlation_id = str(uuid.uuid4())
token = set_correlation_id(correlation_id)
try:
await _do_re_resolve_with_resources(geo_cache, settings, http_session)
finally:
reset_correlation_id(token)
async def _do_re_resolve_with_resources(
geo_cache: GeoCache,
settings: Settings,
http_session: ClientSession,
) -> None:
"""Inner re-resolve logic that runs with correlation context set."""
async def _do_re_resolve() -> None:
async with task_db(settings) as db:
@@ -61,10 +86,10 @@ async def _run_re_resolve_with_resources(
unresolved_ips = await geo_cache.get_unresolved_ips(db)
if not unresolved_ips:
log.debug("geo_re_resolve_skip", reason="no_unresolved_ips")
log.debug("geo_re_resolve_skip", correlation_id=get_correlation_id(), reason="no_unresolved_ips")
return
log.info("geo_re_resolve_start", unresolved=len(unresolved_ips))
log.info("geo_re_resolve_start", correlation_id=get_correlation_id(), unresolved=len(unresolved_ips))
# Clear the negative cache so these IPs are eligible for fresh API calls.
await geo_cache.clear_neg_cache()
@@ -78,6 +103,7 @@ async def _run_re_resolve_with_resources(
)
log.info(
"geo_re_resolve_complete",
correlation_id=get_correlation_id(),
retried=len(unresolved_ips),
resolved=resolved_count,
)