PPR — Полные требования

Содержание

1. README.md
2. PostgreSQL: описание данных
3. Телеметрия — общие требования
4. Логи
5. Шедулеры
6. Исходящие HTTP-запросы
7. Входящие HTTP-запросы

---

1. README.md

Файл readme.md в корне репозитория обязателен. Должен содержать:

1. Назначение сервиса — что делает, зачем нужен.

   Пример: «Blacklist сервис хранит чёрные списки исполнителей и отвечает другим сервисам, находится ли исполнитель в ЧС компании или проекта.»

2. Таблица зависимостей — какие сервисы/БД используются, каким способом и зачем.

   другой сервис	способ	зачем нужно
   postgres	postgres	храним и проверяем черные списки
   redis	redis	кеш запросов к постгрес
   dap-server	API	проверяет наличие в ЧС перед записью на задание
   kafka	kafka	пишет в топик dap_blacklist_updates об изменениях в ЧС

---

2. PostgreSQL: описание данных

Актуально только если сервис использует PostgreSQL.

1. Каждая таблица должна иметь комментарий:

   COMMENT ON TABLE users IS 'Информация о пользователях. Используется для авторизации и поиска.';

2. Каждая колонка с персональными данными (адрес, телефон, email, имя и т.д.) — тег [pd]:

   COMMENT ON COLUMN users.first_name IS '[pd]';

3. Каждая колонка с секретами (пароли, хэши, токены и т.п.) — тег [secret]:

   COMMENT ON COLUMN users.password IS '[secret] хэш пароля';

Для прочих колонок комментарии опциональны.

---

3. Телеметрия — общие требования

Используются библиотеки OpenTelemetry.

1. Сервис отдаёт трейсы и метрики по OTLP (http/protobuf).

2. Есть эндпоинт с метриками в формате Prometheus.

3. Полезная работа сопровождается бизнес-метриками (минимум: счётчик выполненной работы + счётчик ошибок).

   Пример (blacklist-сервис):

   # Результат проверки наличия испа в ЧС
   dap_blacklist_check_results_total{result="NOT_BANNED", reason=""}
   dap_blacklist_check_results_total{result="BANNED", reason="PROJECT_BLACKLIST"}
   dap_blacklist_check_results_total{result="ERROR", reason="Database connection failed"}

4. Формат имени бизнес-метрики:

   • Начинается с dap_ или ventrago_
   • Описывает что показывает метрика
   • Единицы измерения (запросы, байты, секунды, рубли и т.д.) — если не очевидно из названия
   • Для Counter обязательно окончание _total

---

4. Логи

В логах НЕ должно быть:

• Секретов (токены, пароли и т.п.)
• Персональных данных (ФИО + телефон/email и другие комбинации). В идеале — только ID.
• Дампов HTTP или SQL запросов/ответов.

Рекомендуется прочитать: https://wiki.ventrago.ru/books/telemetriia/page/kak-pravilno-pisat-logi

---

5. Шедулеры

Актуально только если есть фоновые задачи по расписанию.

Все метрики шедулеров должны иметь лейблы:

• code_function — имя функции шедулера в коде
• repeatability — single (один раз за жизнь приложения) или regular (периодически)

Название метрики	Тип	Описание
scheduler_end_time_timestamp_seconds	Gauge	Unix timestamp (сек) последнего завершения
scheduler_interval_seconds	Gauge	Интервал работы в секундах
scheduler_start_time_timestamp_seconds	Gauge	Unix timestamp (сек) последнего запуска
scheduler_status	Gauge	0 = успех, ненулевое = ошибка
scheduler_execution_time_seconds_total	Counter	Суммарное время работы в секундах

---

6. Исходящие HTTP-запросы

Актуально только если сервис делает исходящие HTTP-запросы.

1. Спан на каждый исходящий запрос с атрибутами:

   • span.kind="client"
   • http.request.method
   • http.response.status_code
   • server.address
   • url.full

2. Пропагация контекста — заголовки трейсинга передаются следующему сервису. Признак корректной пропагации: входящие и исходящие спаны чередуются «лесенкой» в трейсе.

3. Histogram-метрика http_client_request_duration_seconds с лейблами:

   • http_request_method — метод (GET, POST и т.д.)
   • http_response_status_code или error_type — код ответа или тип ошибки
   • server_address — адрес сервера (например, api.example.com)

---

7. Входящие HTTP-запросы

Актуально только если сервис принимает входящие HTTP-запросы.

1. Спан на каждый входящий запрос с атрибутами:

   • span.kind="server"
   • http.request.method
   • http.response.status_code
   • http.route
   • client.address
   • url.path

2. Пропагация контекста — аналогично исходящим запросам.

3. Histogram-метрика http_server_request_duration_seconds с лейблами:

   • http_request_method — метод (GET, POST и т.д.)
   • http_response_status_code или error_type — код ответа или тип ошибки
   • http_route — паттерн URL, не конкретный путь с ID. ✅ Валидно: /api/users/{user_id} ❌ Невалидно: /api/users/12345