Device Metrics Analytics

Тестовое задание. REST-сервис на FastAPI для сбора показаний условных устройств, хранения метрик и расчета аналитики по устройствам и пользователям.

Что реализовано

• прием статистики устройства в формате {"x": float, "y": float, "z": float}
• хранение данных в БД через SQLAlchemy
• анализ показаний устройства за произвольный период и за все время
• расчет метрик min, max, count, sum, median для x, y, z
• добавление пользователей
• добавление и привязка устройств к пользователям
• анализ по пользователю:
  • суммарно по всем его устройствам
  • отдельно по каждому устройству
• асинхронный запуск аналитики через Celery и Redis
• контейнеризация через Docker и docker-compose
• нагрузочный сценарий через Locust

Стек

• Python 3.8+
• FastAPI
• SQLAlchemy 2.0
• Celery
• Redis
• PostgreSQL в docker-compose
• SQLite по умолчанию для ручного локального запуска

Структура проекта

app/
  api/               HTTP endpoints
  core/              конфигурация
  db/                модели и сессии БД
  services/          логика аналитики
  tasks/             Celery-задачи
load_tests/
  results/           CSV-артефакты locust
tests/               pytest-проверки
locustfile.py        сценарий нагрузочного теста
docker-compose.yml   локальное окружение
Dockerfile           контейнер приложения

API

Swagger UI после запуска доступен по адресу http://localhost:8000/docs.

Основные endpoints

• GET /api/v1/health — краткий статус API, БД, Redis и Celery
• POST /api/v1/users — создать пользователя
• GET /api/v1/users/{user_id} — получить пользователя
• POST /api/v1/devices — зарегистрировать устройство
• GET /api/v1/devices/{device_id} — получить устройство
• PATCH /api/v1/devices/{device_id} — обновить имя или владельца устройства
• POST /api/v1/devices/{device_id}/metrics — сохранить метрику устройства
• GET /api/v1/devices/{device_id}/analysis — аналитика по устройству
• GET /api/v1/users/{user_id}/analysis — аналитика по пользователю

Асинхронная аналитика

• POST /api/v1/analysis/devices/{device_id}
• POST /api/v1/analysis/users/{user_id}
• GET /api/v1/tasks/{task_id}

start_at и end_at передаются query-параметрами в ISO 8601. По дефолту, анализ выполняется за все время.

Примеры запросов

Создание пользователя:

curl -X POST http://localhost:8000/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"alice@example.com"}'

Создание устройства:

curl -X POST http://localhost:8000/api/v1/devices \
  -H "Content-Type: application/json" \
  -d '{"id":"device-1","name":"Tracker #1","user_id":"<user_id>"}'

Отправка метрики:

curl -X POST http://localhost:8000/api/v1/devices/device-1/metrics \
  -H "Content-Type: application/json" \
  -d '{"x": 12.3, "y": 4.5, "z": 6.7}'

Аналитика по устройству:

curl "http://localhost:8000/api/v1/devices/device-1/analysis?start_at=2026-01-01T00:00:00Z&end_at=2026-12-31T23:59:59Z"

Локальный запуск

Основной способ запуска и проверки сервиса: docker compose. В этом режиме сразу поднимаются FastAPI, Redis, Celery worker, PostgreSQL и Locust, а аналитика всегда выполняется через настоящую очередь задач.

docker compose up --build

После старта:

• API: http://127.0.0.1:8000
• Swagger UI: http://127.0.0.1:8000/docs
• Locust UI: http://127.0.0.1:8089

Проверка инфраструктуры:

• GET /api/v1/health должен возвращать database = "ok" redis = "ok" celery = "ok"

Состав Compose-окружения

При запуске через docker compose поднимаются сервисы:

• api — FastAPI
• worker — Celery worker
• postgres — PostgreSQL
• redis — брокер и backend Celery
• locust — UI для ручного нагрузочного тестирования

Проверка

Функциональный smoke-test:

.venv/bin/pytest -q

Результат последнего прогона:

5 passed

Нагрузочное тестирование

Готовый сценарий находится в locustfile.py. Подробный отчет лежит в load_tests/report.md.

Краткий итог прогона 2026-05-01:

• 20 пользователей, 30 секунд, 0% ошибок
• стек: docker-compose (FastAPI + PostgreSQL + Redis + Celery worker)
• суммарная производительность: 63.05 req/s
• p95 по всем запросам: 15 ms
• максимальная зафиксированная задержка: 40 ms