feat: усилить кэш задач и наблюдаемость

RomanVetrov · RomanVetrov · commit 77e157e0b9d3 · 2026-03-16T21:07:26.000+03:00
- перевести инвалидацию кэша задач в фоновый режим с логированием ошибок
- добавить hit/miss метрики кэша списка задач в Prometheus
- обновить Grafana dashboard и покрыть сценарии тестами
diff --git a/app/cache/tasks_list.py b/app/cache/tasks_list.py
@@ -8,6 +8,7 @@
 from redis.asyncio import Redis
 from redis.exceptions import RedisError
 
+from app.metrics import observe_tasks_cache_hit, observe_tasks_cache_miss
 from app.schemas.task import TaskRead
 
 logger = getLogger(__name__)
@@ -51,18 +52,23 @@ async def get_cached_tasks_list(redis: Redis, cache_key: str) -> list[TaskRead]
     try:
         raw_payload = await redis.get(cache_key)
     except RedisError:
+        observe_tasks_cache_miss()
         logger.warning(
             "Не удалось прочитать кэш списка задач",
             extra={"cache_key": cache_key},
         )
         return None
 
     if raw_payload is None:
+        observe_tasks_cache_miss()
         return None
 
     try:
-        return _TASKS_LIST_ADAPTER.validate_json(raw_payload)
+        tasks = _TASKS_LIST_ADAPTER.validate_json(raw_payload)
+        observe_tasks_cache_hit()
+        return tasks
     except ValidationError:
+        observe_tasks_cache_miss()
         await delete_cached_tasks_list(redis, cache_key)
         return None
 
diff --git a/app/metrics.py b/app/metrics.py
@@ -14,6 +14,16 @@
     ["method", "path"],
 )
 
+TASKS_CACHE_HITS_TOTAL = Counter(
+    "tasks_cache_hits_total",
+    "Количество попаданий в кэш списка задач.",
+)
+
+TASKS_CACHE_MISSES_TOTAL = Counter(
+    "tasks_cache_misses_total",
+    "Количество промахов кэша списка задач.",
+)
+
 
 def observe_http_request(
     *,
@@ -28,5 +38,15 @@ def observe_http_request(
     )
 
 
+def observe_tasks_cache_hit() -> None:
+    """Регистрирует попадание в кэш списка задач."""
+    TASKS_CACHE_HITS_TOTAL.inc()
+
+
+def observe_tasks_cache_miss() -> None:
+    """Регистрирует промах кэша списка задач."""
+    TASKS_CACHE_MISSES_TOTAL.inc()
+
+
 def render_metrics() -> tuple[bytes, str]:
     return generate_latest(), CONTENT_TYPE_LATEST
diff --git a/app/routes/tasks.py b/app/routes/tasks.py
@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import asyncio
+from logging import getLogger
 from uuid import UUID
 from typing import Annotated
 
@@ -33,15 +35,30 @@
 DbSession = Annotated[AsyncSession, Depends(get_db)]
 RedisClient = Annotated[Redis, Depends(get_redis)]
 TaskFilters = Annotated[TaskListFilters, Depends()]
+logger = getLogger(__name__)
 
 _DUE_DATE_ERROR = HTTPException(
     status_code=status.HTTP_400_BAD_REQUEST,
     detail="Дедлайн не может быть в прошлом",
 )
 
 
-async def _invalidate_user_tasks_cache(redis: Redis, user_id: UUID) -> None:
-    await delete_cached_tasks_list_for_user(redis, user_id)
+def _schedule_invalidate_user_tasks_cache(redis: Redis, user_id: UUID) -> None:
+    """Запускает инвалидацию кэша списка задач в фоне (fire-and-forget).
+    Исключения в фоновой задаче логируются и не пробрасываются в вызывающий код.
+    """
+
+    async def _run() -> None:
+        try:
+            await delete_cached_tasks_list_for_user(redis, user_id)
+        except Exception:  # noqa: BLE001
+            logger.warning(
+                "Не удалось инвалидировать кэш задач пользователя",
+                extra={"user_id": str(user_id)},
+                exc_info=True,
+            )
+
+    asyncio.create_task(_run())
 
 
 @router.post(
@@ -59,7 +76,7 @@ async def create_task(
         task = await task_service.create_task(session, current_user, payload)
     except InvalidDueDate:
         raise _DUE_DATE_ERROR
-    await _invalidate_user_tasks_cache(redis, current_user.id)
+    _schedule_invalidate_user_tasks_cache(redis, current_user.id)
     return TaskRead.model_validate(task)
 
 
@@ -124,7 +141,7 @@ async def update_task(
         updated = await task_service.update_task(session, task, payload)
     except InvalidDueDate:
         raise _DUE_DATE_ERROR
-    await _invalidate_user_tasks_cache(redis, task.user_id)
+    _schedule_invalidate_user_tasks_cache(redis, task.user_id)
     return TaskRead.model_validate(updated)
 
 
@@ -138,7 +155,7 @@ async def delete_task(
     redis: RedisClient,
 ) -> TaskDeleted:
     task_id = await task_service.delete_task(session, task)
-    await _invalidate_user_tasks_cache(redis, task.user_id)
+    _schedule_invalidate_user_tasks_cache(redis, task.user_id)
     return TaskDeleted(id=task_id)
 
 
@@ -154,7 +171,7 @@ async def attach_tag_to_task(
     redis: RedisClient,
 ) -> TaskTagLink:
     await tag_service.attach_tag_to_task(session, task, tag)
-    await _invalidate_user_tasks_cache(redis, task.user_id)
+    _schedule_invalidate_user_tasks_cache(redis, task.user_id)
     return TaskTagLink(task_id=task.id, tag_id=tag.id)
 
 
@@ -169,5 +186,5 @@ async def detach_tag_from_task(
     redis: RedisClient,
 ) -> TaskTagLink:
     await tag_service.detach_tag_from_task(session, task, tag)
-    await _invalidate_user_tasks_cache(redis, task.user_id)
+    _schedule_invalidate_user_tasks_cache(redis, task.user_id)
     return TaskTagLink(task_id=task.id, tag_id=tag.id)
diff --git a/monitoring/grafana/provisioning/dashboards/default.yml b/monitoring/grafana/provisioning/dashboards/default.yml
@@ -6,7 +6,7 @@ providers:
     folder: Task Manager
     type: file
     disableDeletion: false
-    allowUiUpdates: true
+    allowUiUpdates: false
     updateIntervalSeconds: 10
     options:
       path: /etc/grafana/provisioning/dashboards/json
diff --git a/monitoring/grafana/provisioning/dashboards/json/task-manager-observability.json b/monitoring/grafana/provisioning/dashboards/json/task-manager-observability.json
@@ -834,6 +834,169 @@
       ],
       "title": "Security сигналы: 401/403/429 (за 5 минут)",
       "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "thresholds"
+          },
+          "mappings": [],
+          "max": 1,
+          "min": 0,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "red",
+                "value": null
+              },
+              {
+                "color": "orange",
+                "value": 0.4
+              },
+              {
+                "color": "green",
+                "value": 0.7
+              }
+            ]
+          },
+          "unit": "percentunit"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 6,
+        "w": 6,
+        "x": 0,
+        "y": 37
+      },
+      "id": 11,
+      "options": {
+        "colorMode": "background",
+        "graphMode": "none",
+        "justifyMode": "auto",
+        "orientation": "auto",
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ],
+          "fields": "",
+          "values": false
+        },
+        "textMode": "auto"
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "sum(increase(tasks_cache_hits_total[5m])) / clamp_min(sum(increase(tasks_cache_hits_total[5m])) + sum(increase(tasks_cache_misses_total[5m])), 1)",
+          "legendFormat": "cache hit ratio",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "Кэш /tasks hit ratio (5м)",
+      "type": "stat"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 2,
+            "pointSize": 4,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "never",
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "reqps"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 6,
+        "w": 18,
+        "x": 6,
+        "y": 37
+      },
+      "id": 12,
+      "options": {
+        "legend": {
+          "calcs": [
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "sum(rate(tasks_cache_hits_total[5m]))",
+          "legendFormat": "cache hit/sec",
+          "range": true,
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "sum(rate(tasks_cache_misses_total[5m]))",
+          "legendFormat": "cache miss/sec",
+          "range": true,
+          "refId": "B"
+        }
+      ],
+      "title": "Кэш /tasks hit/miss в секунду",
+      "type": "timeseries"
     }
   ],
   "refresh": "5s",
@@ -911,6 +1074,6 @@
   "timezone": "",
   "title": "Task Manager API - Observability",
   "uid": "task-manager-observability",
-  "version": 5,
+  "version": 6,
   "weekStart": ""
 }
diff --git a/tests/api/test_tasks_routes.py b/tests/api/test_tasks_routes.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 import json
 from datetime import UTC, date, datetime, timedelta
 from types import SimpleNamespace
@@ -100,6 +101,7 @@ async def test_create_task_returns_201(
             "priority": "medium",
         },
     )
+    await asyncio.sleep(0.05)  # дать выполниться фоновой инвалидации кэша
 
     assert response.status_code == 201
     assert response.json()["title"] == "New task"
@@ -341,6 +343,7 @@ async def test_update_task_returns_200(
         f"/api/v1/tasks/{original.id}",
         json={"title": "Updated"},
     )
+    await asyncio.sleep(0.05)  # дать выполниться фоновой инвалидации кэша
 
     assert response.status_code == 200
     assert response.json()["title"] == "Updated"
@@ -391,6 +394,7 @@ async def test_delete_task_returns_deleted_id(
     monkeypatch.setattr(tasks_routes.task_service, "delete_task", delete_task)
 
     response = await client.delete(f"/api/v1/tasks/{task.id}")
+    await asyncio.sleep(0.05)  # дать выполниться фоновой инвалидации кэша
 
     assert response.status_code == 200
     assert response.json() == {"id": str(task.id)}
@@ -417,6 +421,7 @@ async def test_attach_tag_to_task_returns_201(
     monkeypatch.setattr(tasks_routes.tag_service, "attach_tag_to_task", attach_tag)
 
     response = await client.post(f"/api/v1/tasks/{task.id}/tags/{tag.id}")
+    await asyncio.sleep(0.05)  # дать выполниться фоновой инвалидации кэша
 
     assert response.status_code == 201
     assert response.json() == {"task_id": str(task.id), "tag_id": str(tag.id)}
@@ -444,6 +449,7 @@ async def test_detach_tag_from_task_returns_200(
     monkeypatch.setattr(tasks_routes.tag_service, "detach_tag_from_task", detach_tag)
 
     response = await client.delete(f"/api/v1/tasks/{task.id}/tags/{tag.id}")
+    await asyncio.sleep(0.05)  # дать выполниться фоновой инвалидации кэша
 
     assert response.status_code == 200
     assert response.json() == {"task_id": str(task.id), "tag_id": str(tag.id)}
diff --git a/tests/unit/cache/test_tasks_list_cache.py b/tests/unit/cache/test_tasks_list_cache.py
diff --git a/tests/unit/routes/test_tasks_fire_forget.py b/tests/unit/routes/test_tasks_fire_forget.py
