feat: подключить базовую трассировку OpenTelemetry и Jaeger

Что сделано:
- добавлены зависимости OpenTelemetry и обновлён lock-файл
- добавлен модуль telemetry с OTLP-экспортом, сэмплингом и авто-инструментацией FastAPI, SQLAlchemy, Redis
- подключена инициализация и корректное завершение telemetry в lifecycle приложения
- добавлены ручные span на сервисном уровне auth и tasks для читаемого дерева вызовов
- добавлен сервис Jaeger и OTel-переменные окружения в docker-compose

Author: RomanVetrov

app/config.py

@@ -15,6 +15,11 @@ class Settings(BaseSettings):
     ARGON_HASH_LEN: int = 32
     ARGON_SALT_LEN: int = 16
     ARGON_MAX_PASSWORD_LEN: int = 1024  # basic DoS guard
+    OTEL_ENABLED: bool = True
+    OTEL_SERVICE_NAME: str = "task-manager-api"
+    OTEL_EXPORTER_OTLP_ENDPOINT: str = "http://localhost:4317"
+    OTEL_EXPORTER_OTLP_INSECURE: bool = True
+    OTEL_SAMPLE_RATIO: float = 1.0
 
     model_config = SettingsConfigDict(
         env_file=".env",

app/main.py

@@ -11,6 +11,7 @@
 from app.routes.metrics import router as metrics_router
 from app.routes.tags import router as tags_router
 from app.routes.tasks import router as tasks_router
+from app.telemetry import setup_telemetry, shutdown_telemetry
 
 
 @asynccontextmanager
@@ -19,6 +20,7 @@ async def lifespan(app: FastAPI):
     try:
         yield
     finally:
+        shutdown_telemetry()
         await redis_client.aclose()
 
 
@@ -31,6 +33,8 @@ async def lifespan(app: FastAPI):
     lifespan=lifespan,
 )
 
+setup_telemetry(app)
+
 # middleware регистрируются в обратном порядке (луковица).
 # RequestID должен сработать первым, поэтому добавляем его последним.
 app.add_middleware(MetricsMiddleware)

app/services/auth.py

@@ -4,12 +4,15 @@
 
 from uuid import UUID
 
+from opentelemetry import trace
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.models.user import User
 from app.repositories import user_repo
 from app.security.password import get_dummy_hash, hash_password, verify_password
 
+tracer = trace.get_tracer(__name__)
+
 
 class UserAlreadyExists(Exception):
     """Email уже занят другим пользователем."""
@@ -25,23 +28,29 @@ class UserInactive(Exception):
 
 async def register_user(session: AsyncSession, email: str, password: str) -> User:
     """Регистрирует нового пользователя. Поднимает UserAlreadyExists если email занят."""
-    if await user_repo.get_user_by_email(session, email):
-        raise UserAlreadyExists(email)
-    pass_hash = await hash_password(password=password)
-    return await user_repo.create_user(session, email=email, hashed_password=pass_hash)
+    with tracer.start_as_current_span("auth.register_user"):
+        if await user_repo.get_user_by_email(session, email):
+            raise UserAlreadyExists(email)
+        pass_hash = await hash_password(password=password)
+        return await user_repo.create_user(
+            session,
+            email=email,
+            hashed_password=pass_hash,
+        )
 
 
 async def authenticate_user(
     session: AsyncSession, email: str, password: str
 ) -> User | None:
     """Проверяет email + пароль. Возвращает пользователя или None если данные неверны."""
-    user = await user_repo.get_user_by_email(session, email)
-    # Всегда прогоняем Argon2, даже если email не найден — защита от тайминг-атаки.
-    # Без этого атакующий может по времени ответа определить, существует ли email.
-    hashed = user.hashed_password if user else get_dummy_hash()
-    if not await verify_password(password=password, hashed_password=hashed):
-        return None
-    return user
+    with tracer.start_as_current_span("auth.authenticate_user"):
+        user = await user_repo.get_user_by_email(session, email)
+        # Всегда прогоняем Argon2, даже если email не найден — защита от тайминг-атаки.
+        # Без этого атакующий может по времени ответа определить, существует ли email.
+        hashed = user.hashed_password if user else get_dummy_hash()
+        if not await verify_password(password=password, hashed_password=hashed):
+            return None
+        return user
 
 
 async def authenticate_active_user(
@@ -62,9 +71,10 @@ async def authenticate_active_user(
 
 async def validate_refresh_subject(session: AsyncSession, user_id: UUID) -> User:
     """Проверяет, что пользователь для refresh существует и активен."""
-    user = await user_repo.get_user_by_id(session, user_id)
-    if not user:
-        raise UserNotFound
-    if not user.is_active:
-        raise UserInactive
-    return user
+    with tracer.start_as_current_span("auth.validate_refresh_subject"):
+        user = await user_repo.get_user_by_id(session, user_id)
+        if not user:
+            raise UserNotFound
+        if not user.is_active:
+            raise UserInactive
+        return user

app/services/task.py

@@ -4,39 +4,46 @@
 from datetime import date
 from uuid import UUID
 
+from opentelemetry import trace
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.models.task import Task
 from app.models.user import User
 from app.repositories import task_repo
 from app.schemas.task import TaskCreate, TaskUpdate
 
+tracer = trace.get_tracer(__name__)
+
 
 class InvalidDueDate(Exception):
     """Дедлайн задачи не может быть в прошлом."""
 
 
 async def create_task(session: AsyncSession, user: User, payload: TaskCreate) -> Task:
     """Создаёт задачу. Поднимает InvalidDueDate если дедлайн в прошлом."""
-    if payload.due_date and payload.due_date < date.today():
-        raise InvalidDueDate
-    return await task_repo.create_task(session, user, **payload.model_dump())
+    with tracer.start_as_current_span("tasks.create_task"):
+        if payload.due_date and payload.due_date < date.today():
+            raise InvalidDueDate
+        return await task_repo.create_task(session, user, **payload.model_dump())
 
 
 async def get_user_tasks(session: AsyncSession, user: User) -> Sequence[Task]:
     """Возвращает все задачи пользователя."""
-    return await task_repo.get_tasks_by_user(session, user)
+    with tracer.start_as_current_span("tasks.get_user_tasks"):
+        return await task_repo.get_tasks_by_user(session, user)
 
 
 async def update_task(session: AsyncSession, task: Task, payload: TaskUpdate) -> Task:
     """Обновляет задачу. Поднимает InvalidDueDate если дедлайн в прошлом."""
-    updates = payload.model_dump(exclude_unset=True)
-    due_date = updates.get("due_date")
-    if due_date is not None and due_date < date.today():
-        raise InvalidDueDate
-    return await task_repo.update_task(session, task, **updates)
+    with tracer.start_as_current_span("tasks.update_task"):
+        updates = payload.model_dump(exclude_unset=True)
+        due_date = updates.get("due_date")
+        if due_date is not None and due_date < date.today():
+            raise InvalidDueDate
+        return await task_repo.update_task(session, task, **updates)
 
 
 async def delete_task(session: AsyncSession, task: Task) -> UUID:
     """Удаляет задачу и возвращает её id."""
-    return await task_repo.delete_task(session, task)
+    with tracer.start_as_current_span("tasks.delete_task"):
+        return await task_repo.delete_task(session, task)

app/telemetry.py

@@ -0,0 +1,47 @@
+from fastapi import FastAPI
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+from opentelemetry.instrumentation.redis import RedisInstrumentor
+from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk.trace.sampling import ParentBased, TraceIdRatioBased
+
+from app.config import settings
+from app.database import engine
+
+_initialized = False
+
+
+def setup_telemetry(app: FastAPI) -> None:
+    """Инициализирует OpenTelemetry и авто-инструментацию приложения."""
+    global _initialized
+    if _initialized or not settings.OTEL_ENABLED:
+        return
+
+    provider = TracerProvider(
+        resource=Resource.create({"service.name": settings.OTEL_SERVICE_NAME}),
+        sampler=ParentBased(TraceIdRatioBased(settings.OTEL_SAMPLE_RATIO)),
+    )
+    exporter = OTLPSpanExporter(
+        endpoint=settings.OTEL_EXPORTER_OTLP_ENDPOINT,
+        insecure=settings.OTEL_EXPORTER_OTLP_INSECURE,
+    )
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)
+
+    FastAPIInstrumentor.instrument_app(app, excluded_urls="/metrics,/api/v1/health")
+    SQLAlchemyInstrumentor().instrument(engine=engine.sync_engine)
+    RedisInstrumentor().instrument()
+    _initialized = True
+
+
+def shutdown_telemetry() -> None:
+    """Корректно завершает экспортёр при остановке приложения."""
+    if not settings.OTEL_ENABLED:
+        return
+    provider = trace.get_tracer_provider()
+    if isinstance(provider, TracerProvider):
+        provider.shutdown()

docker-compose.yml

@@ -49,13 +49,30 @@ services:
       ACCESS_TOKEN_EXPIRE_MINUTES: 10
       REFRESH_TOKEN_EXPIRE_DAYS: 7
       WEB_CONCURRENCY: 4
+      OTEL_ENABLED: "true"
+      OTEL_SERVICE_NAME: task-manager-api
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://jaeger:4317
+      OTEL_EXPORTER_OTLP_INSECURE: "true"
+      OTEL_SAMPLE_RATIO: "1.0"
     ports:
       - "8000:8000"
     depends_on:
       postgres:
         condition: service_healthy
       redis:
         condition: service_healthy
+      jaeger:
+        condition: service_started
+    restart: unless-stopped
+
+  jaeger:
+    image: jaegertracing/all-in-one:1.64.0
+    container_name: task-manager-jaeger
+    ports:
+      - "16686:16686"
+      - "4317:4317"
+    environment:
+      COLLECTOR_OTLP_ENABLED: "true"
     restart: unless-stopped
 
   prometheus:

pyproject.toml

@@ -18,6 +18,12 @@ dependencies = [
     "uvicorn[standard]>=0.41.0",
     "structlog>=25.5.0",
     "prometheus-client>=0.24.1",
+    "opentelemetry-api>=1.40.0",
+    "opentelemetry-sdk>=1.40.0",
+    "opentelemetry-exporter-otlp>=1.40.0",
+    "opentelemetry-instrumentation-fastapi>=0.61b0",
+    "opentelemetry-instrumentation-sqlalchemy>=0.61b0",
+    "opentelemetry-instrumentation-redis>=0.61b0",
 ]
 
 [dependency-groups]