mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 08:56:21 +02:00
Structure the tech specs directory (#836)
Tech spec some subdirectories for different languages
This commit is contained in:
cybermaggedon
GitHub
parent
48da6c5f8b
commit
e7efb673ef
423 changed files with 0 additions and 0 deletions
213
docs/tech-specs/ru/logging-strategy.ru.md
Normal file
213
docs/tech-specs/ru/logging-strategy.ru.md
Normal file
|
|
@ -0,0 +1,213 @@
|
|||
---
|
||||
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 |
|
||||
Loading…
Add table
Add a link
Reference in a new issue