Отладка и разработка

Методика отладки программного обеспечения ЛиманИСУ 2.0 охватывает все компоненты системы: Python-сервисы (FastAPI), Java-сервисы (Spring), фронтенд (React) и инфраструктурные компоненты (PostgreSQL, ClickHouse, NATS, MinIO).

Инструменты отладки

Категория	Инструменты
Контейнерные сервисы	docker-compose logs, docker-compose logs <имя-сервиса>
Python-сервисы	PyCharm / VS Code с дебаггером
Java-сервисы	IntelliJ IDEA / Spring Boot DevTools
Мониторинг сообщений	MQTT Explorer (для MQTT/NATS), mqttui (CLI)
PostgreSQL	DBeaver, pgAdmin
ClickHouse	DBeaver, clickhouse-client
Объектное хранилище	MinIO Console, awscli
NATS	NATS CLI, MQTT Explorer

---

Режимы отладки

Python-сервисы

Переменная окружения DEBUG=true включает расширенное логирование:

export DEBUG=true
python main.py

Или в Docker:

docker-compose exec <service-name> bash -c "export DEBUG=true && python main.py"

Java-сервисы

Настройка уровня логирования в application.yml:

logging:
  level:
    root: DEBUG
    org.springframework.web: TRACE

Для включения health/info/metrics endpoints:

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics

---

Настройка PyCharm для отладки Python-сервисов

Конфигурация запуска для FastAPI Backend Diagnost:

{
  "name": "diagnost-backend-debug",
  "type": "python",
  "request": "launch",
  "module": "uvicorn",
  "args": ["src.main:app"],
  "env": {
    "DEBUG": "true",
    "S3_ACCESS_KEY": "your-key",
    "S3_SECRET_KEY": "your-secret",
    "S3_ENDPOINT_URL": "your-s3-endpoint",
    "S3_BUCKET": "your-bucket",
    "CH_HOST": "clickhouse",
    "CH_PORT": "9000",
    "CH_DATABASE": "default",
    "CH_USERNAME": "user",
    "CH_PASSWORD": "password"
  }
}

Отладка с uvicorn

При запуске через PyCharm используйте модуль uvicorn с аргументом src.main:app. Для hot-reload добавьте --reload в args.

---

Отладка инфраструктурных компонентов

Базы данных

Компонент	Инструменты	Контрольные точки
PostgreSQL	DBeaver, pgAdmin	Проверка подключения, тестовые запросы
ClickHouse	DBeaver, clickhouse-client	Мониторинг вставки данных, запросы к системным таблицам
MinIO	MinIO Console, awscli	Проверка доступа к бакетам, загрузка/скачивание файлов

Системы обмена сообщениями

Компонент	Инструменты	Методика проверки
NATS	NATS CLI, MQTT Explorer	Подписка на темы, проверка доставки сообщений
NanoMQ	MQTT Explorer, mqttui	Подписка на топики телеметрии

---

Отладка по сервисам

FastAPI Backend Diagnost

• Включение: DEBUG=true в .env
• Контрольные точки:
  • Подключение к S3 (проверка credentials)
  • Запросы к ClickHouse
  • Заголовки CORS
• Типовые ошибки:
  • Ошибки доступа к S3/ClickHouse
  • Ошибки форматов данных

Defect Detection Service

• Включение: DEBUG=true в .env
• Контрольные точки:
  • Обработка файлов в S3
  • Публикация результатов в NATS
  • Сохранение результатов в ClickHouse
• Типовые ошибки:
  • Потеря сообщений в NATS
  • Ошибки спектрального анализа

Equipment Mode Service

• Включение: DEBUG=true (по умолчанию)
• Контрольные точки:
  • Время обработки NATS-сообщения
  • Сохранение в ClickHouse

Event Journal Service

• Контрольные точки:
  • Запись и чтение событий из ClickHouse
  • Подписка на события через NATS

Notification Service

• Включение: DEBUG=true включает логирование email/SMS (без секретов)
• Проверка:

docker-compose exec notification-service bash -c "export DEBUG=true && python main.py"

Telemetry Limits Service

• Включение: DEBUG=true (по умолчанию)
• Контрольные точки:
  • Границы телеметрии
  • Отсутствие телеметрии в течение заданного времени

Telemetry Service

• Контрольные точки:
  • Фильтрация телеметрии по времени и точкам
  • Работа API

Bearing Reference Book Service

• Контрольные точки:
  • Доступность API CRUD
  • Подключение к PostgreSQL

Defects Reference Book Service

• Контрольные точки:
  • Доступность API CRUD
  • Подключение к PostgreSQL

Remaining Resource Forecast Service

• Контрольные точки:
  • Сохранение прогнозов в ClickHouse
  • Публикация результатов в NATS

lisu-crud (Java)

• Контрольные точки:
  • Авторизация Keycloak
  • CRUD по пользователям, телеметрии, журналам

report-distributor (Java)

• Контрольные точки:
  • Генерация отчетов (PDF/DOCX)
  • Отправка email
  • Запросы к PostgreSQL

backup-distributor (Java)

• Контрольные точки:
  • Создание/восстановление бэкапов
  • Логи Cron-задач

limanisu-front (React)

• Контрольные точки:
  • Проверка переменных окружения REACT_APP_*
  • Подключения к API через REACT_APP_BASE_URL, REACT_APP_CHARTS_URL и др.

Ping for Larus

• Контрольные точки:
  • Подключение к lisu-backend
  • Ответ от Keycloak

---

Сводная таблица DEBUG по сервисам

Сервис	DEBUG по умолчанию	Ключевые DEBUG-логи
FastAPI Backend Diagnost	false	S3/ClickHouse операции
Equipment Mode Service	true	NATS-сообщения
Telemetry Limits Service	true	Границы телеметрии
Notification Service	false	Тела сообщений
lisu-crud (Java)	--	SQL-запросы, Keycloak взаимодействие
report-distributor	--	Генерация отчетов
backup-distributor	--	Бэкап/восстановление

---

Типовые сценарии отладки

Сервис не запускается

1. Проверить логи контейнера:

docker-compose logs <service-name>

2. Проверить зависимости (СУБД, NATS):

docker-compose ps
docker-compose logs postgres
docker-compose logs nats

3. Проверить переменные окружения в .env

Нет данных в API

1. Проверить логи сервиса на ошибки:

docker-compose logs -f <service-name>

2. Проверить данные напрямую в БД:

-- ClickHouse
SELECT * FROM telemetry ORDER BY timestamp DESC LIMIT 10;

-- PostgreSQL
SELECT COUNT(*) FROM bearings;

3. Проверить подписки в NATS (MQTT Explorer)

Ошибки интеграции

1. Включить DEBUG:

DEBUG=true

2. Проверить URL/credentials внешних сервисов

3. Проверить сетевую доступность:

docker-compose exec <service> curl -v http://target-service:port/health

---

Диагностические запросы

ClickHouse

-- Последние записи телеметрии
SELECT * FROM telemetry ORDER BY timestamp DESC LIMIT 10;

-- Количество событий за последний час
SELECT count() FROM event_journal
WHERE created_at > now() - INTERVAL 1 HOUR;

-- Обнаруженные дефекты
SELECT equipment_id, defect_key, strength, detected_at
FROM detected_defects
ORDER BY detected_at DESC
LIMIT 20;

-- Проверка режимов работы
SELECT equipment_id, mode_id, start_time, end_time, duration
FROM equipment_modes_history
ORDER BY start_time DESC
LIMIT 10;

PostgreSQL

-- Проверка подшипников
SELECT COUNT(*) FROM bearings;

-- Пользователи системы
SELECT id, username, email, active FROM users;

-- Дерево объектов
SELECT id, name, type, path FROM tree ORDER BY path;

-- Измерительные точки
SELECT tn.id, tn.name, tn.topic, tt.name as type_name
FROM telemetry_node tn
JOIN telemetry_type tt ON tn.telemetry_type_id = tt.id;

---

Рекомендации по разработке

Единый формат DEBUG

Во всех Python-сервисах используйте единый формат переменной DEBUG=true/false:

import os
DEBUG = os.getenv("DEBUG", "false").lower() == "true"

Логирование с замером времени

import time
import logging

logger = logging.getLogger(__name__)

start = time.time()
# ... операция ...
logger.debug(f"Operation took {time.time() - start:.2f}s")

Шаблон документирования отладки

Для каждого нового сервиса документируйте отладку по шаблону:

## Отладка <название-сервиса>

### Как включить
```bash
export DEBUG=true && python main.py

Контрольные точки

• ...

Типовые ошибки

• ...

### Java -- включение actuator endpoints

Для Java-сервисов добавляйте actuator endpoints для мониторинга:

```yaml
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics

Безопасность

В production-окружении ограничивайте доступ к actuator endpoints. Не выставляйте DEBUG=true в production.

---

Контроль правильности выполнения

Контроль правильности выполнения программы осуществляется за счет:

• Ведения журналов событий и диагностических сообщений
• Мониторинга доступности микросервисов и внешних компонентов
• Контроля целостности и корректности входных данных
• Обработки исключительных ситуаций и повторных попыток выполнения операций

Самовосстановление

Механизмы самовосстановления обеспечиваются контейнерной инфраструктурой Docker и включают автоматический перезапуск сервисов при сбоях, а также восстановление взаимодействия между компонентами системы. Используйте restart: always в docker-compose.yml.