mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 08:56:21 +02:00
213 lines
11 KiB
Markdown
213 lines
11 KiB
Markdown
---
|
||
layout: default
|
||
title: "Стратегия логирования TrustGraph"
|
||
parent: "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__` модуля:
|
||
|
||
```python
|
||
import logging
|
||
|
||
logger = logging.getLogger(__name__)
|
||
```
|
||
|
||
Имя логгера автоматически используется как метка в Loki для фильтрации и поиска.
|
||
|
||
### 2. Инициализация сервиса
|
||
|
||
Все серверные сервисы автоматически получают конфигурацию логирования через централизованный модуль:
|
||
|
||
```python
|
||
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. Аргументы командной строки
|
||
|
||
Все сервисы поддерживают следующие аргументы логирования:
|
||
|
||
**Уровень логирования:**
|
||
```bash
|
||
--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
|
||
```
|
||
|
||
**Конфигурация Loki:**
|
||
```bash
|
||
--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 # Необязательный пароль для аутентификации
|
||
```
|
||
|
||
**Примеры:**
|
||
```bash
|
||
# По умолчанию - уровень 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**: Критические сообщения о системных сбоях, требующих немедленного внимания
|
||
|
||
#### Формат сообщений
|
||
```python
|
||
# Хорошо - включает контекст
|
||
logger.info(f"Обработка документа: {doc_id}, размер: {doc_size} байт")
|
||
logger.error(f"Не удалось подключиться к базе данных: {error}", exc_info=True)
|
||
|
||
# Плохо - не включает контекст
|
||
logger.info("Обработка документа")
|
||
logger.error("Не удалось подключиться")
|
||
```
|
||
|
||
#### Соображения производительности
|
||
```python
|
||
# Используйте ленивую адресацию для дорогостоящих операций
|
||
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:
|
||
|
||
```python
|
||
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`:
|
||
```python
|
||
# Предыдущий код
|
||
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 |
|