trustgraph/docs/tech-specs/logging-strategy.ru.md

layout	title	parent
default	Стратегия логирования TrustGraph	Russian (Beta)

Стратегия логирования TrustGraph

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Обзор

TrustGraph использует встроенный модуль logging Python для всех операций логирования, с централизованной конфигурацией и опциональной интеграцией с Loki для агрегации логов. Это обеспечивает стандартизированный и гибкий подход к логированию для всех компонентов системы.

Параметры конфигурации по умолчанию

Уровень логирования

• Уровень по умолчанию: INFO
• Указывается через: аргумент командной строки --log-level
• Возможные значения: DEBUG, INFO, WARNING, ERROR, CRITICAL

Направления вывода

1. Консоль (stdout): Всегда включено - обеспечивает совместимость с контейнерными средами
2. Loki: Опциональная централизованная агрегация логов (включена по умолчанию, может быть отключена)

Модуль централизованного логирования

Вся конфигурация логирования управляется модулем trustgraph.base.logging, который предоставляет:

• add_logging_args(parser) - Добавляет стандартные аргументы командной строки для логирования
• setup_logging(args) - Настраивает логирование на основе предоставленных аргументов

Этот модуль используется всеми серверными компонентами:

• Сервисы, основанные на AsyncProcessor
• API Gateway
• Сервер MCP

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

1. Инициализация логгера

Каждый модуль должен создавать свой собственный логгер, используя __name__ модуля:

import logging

logger = logging.getLogger(__name__)

Имя логгера автоматически используется как метка в Loki для фильтрации и поиска.

2. Инициализация сервиса

Все серверные сервисы автоматически получают конфигурацию логирования через централизованный модуль:

from trustgraph.base import add_logging_args, setup_logging
import argparse

def main():
    parser = argparse.ArgumentParser()

    # Добавляем стандартные аргументы логирования (включая конфигурацию Loki)
    add_logging_args(parser)

    # Добавляем свои аргументы для сервиса
    parser.add_argument('--port', type=int, default=8080)

    args = parser.parse_args()
    args = vars(args)

    # Настраиваем логирование в начале запуска
    setup_logging(args)

    # Остальная часть инициализации сервиса
    logger = logging.getLogger(__name__)
    logger.info("Сервис запущен...")

3. Аргументы командной строки

Все сервисы поддерживают следующие аргументы логирования:

Уровень логирования:

--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}

Конфигурация Loki:

--loki-enabled              # Включить Loki (по умолчанию)
--no-loki-enabled           # Отключить Loki
--loki-url URL              # URL для отправки логов в Loki (по умолчанию: http://loki:3100/loki/api/v1/push)
--loki-username USERNAME    # Необязательное имя пользователя для аутентификации
--loki-password PASSWORD    # Необязательный пароль для аутентификации

Примеры:

# По умолчанию - уровень INFO, Loki включен
./my-service

# Режим отладки, только консоль
./my-service --log-level DEBUG --no-loki-enabled

# Пользовательский сервер Loki с аутентификацией
./my-service --loki-url http://loki.prod:3100/loki/api/v1/push \
             --loki-username admin --loki-password secret

4. Переменные окружения

Конфигурация Loki поддерживает использование переменных окружения:

export LOKI_URL=http://loki.prod:3100/loki/api/v1/push
export LOKI_USERNAME=admin
export LOKI_PASSWORD=secret

Аргументы командной строки имеют приоритет над переменными окружения.

5. Рекомендации по логированию

Использование уровней логирования

• DEBUG: Детальная информация для диагностики проблем (значения переменных, вход/выход функций)
• INFO: Общие информационные сообщения (запуск сервиса, загрузка конфигурации, этапы обработки)
• WARNING: Предупреждающие сообщения о потенциально опасных ситуациях (устаревшие функции, восстанавливаемые ошибки)
• ERROR: Сообщения об ошибках о серьезных проблемах (неудачные операции, исключения)
• CRITICAL: Критические сообщения о системных сбоях, требующих немедленного внимания

Формат сообщений

# Хорошо - включает контекст
logger.info(f"Обработка документа: {doc_id}, размер: {doc_size} байт")
logger.error(f"Не удалось подключиться к базе данных: {error}", exc_info=True)

# Плохо - не включает контекст
logger.info("Обработка документа")
logger.error("Не удалось подключиться")

Соображения производительности

# Используйте ленивую адресацию для дорогостоящих операций
logger.debug("Результат дорогостоящей операции: %s", expensive_function())

# Проверяйте уровень логирования для очень дорогих операций DEBUG
if logger.isEnabledFor(logging.DEBUG):
    debug_data = compute_expensive_debug_info()
    logger.debug(f"Данные для отладки: {debug_data}")

6. Структурированное логирование с использованием Loki

Для сложных данных используйте структурированное логирование с дополнительными метками для Loki:

logger.info("Запрос обработан", extra={
    'tags': {
        'request_id': request_id,
        'user_id': user_id,
        'status': 'успешно'
    }
})

Эти метки становятся поисковыми метками в Loki, а также автоматически создаваемыми:

• severity - Уровень логирования (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• logger - Имя модуля (из __name__)

Зависимости

Модуль централизованного логирования требует:

• python-logging-loki - Для интеграции с Loki (необязательно, функционирует без него)

Уже включен в trustgraph-base/pyproject.toml и requirements.txt.

Переход

Для существующего кода:

1. Сервисы, уже использующие AsyncProcessor: Не требуется никаких изменений, интеграция с Loki автоматическая
2. Сервисы, которые не используют AsyncProcessor (api-gateway, mcp-server): Уже обновлены
3. Инструменты командной строки: Не относится - продолжайте использовать print() или простое логирование

Переход от print() к logging:

# Предыдущий код
print(f"Обработка документа {doc_id}")

# Новый код
import logging
logger = logging.getLogger(__name__)
logger.info(f"Обработка документа {doc_id}")

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

• Никогда не логируйте конфиденциальную информацию (пароли, API-ключи, персональные данные, токены)
• Фильтруйте пользовательский ввод перед логированием
• Используйте плейсхолдеры для конфиденциальных полей: user_id=****1234
• Используйте аутентификацию для Loki с помощью --loki-username и --loki-password в производственной среде
• Безопасный транспорт: Используйте HTTPS для URL Loki в производственной среде: https://loki.prod:3100/loki/api/v1/push

Обзор конфигурации

Аргумент	Значение по умолчанию	Переменная окружения	Описание
--log-level	INFO	-	Уровень логирования в консоли и Loki
--loki-enabled	True	-	Включить логирование Loki
--loki-url	http://loki:3100/loki/api/v1/push	LOKI_URL	URL для отправки логов в Loki
--loki-username	None	LOKI_USERNAME	Имя пользователя для аутентификации Loki
--loki-password	None	LOKI_PASSWORD	Пароль для аутентификации Loki