Недостаточная документация и неясная семантика Context Variables

[Benrise]

Проблема

1. Отсутствует описание для operation_id_cvar

В текущем коде переменная operation_id_cvar имеет некорректное/дублирующее описание:

operation_id_cvar: ContextVar[Optional[str]] = ContextVar("operation_id_cvar", default=None)
"""Информация об авторизации с помощью JWE"""  # ⚠️ Это описание дублирует authorization_cvar

2. Отсутствует документация по использованию контекстных переменных

Нет руководства или примеров, объясняющих:

• Назначение каждой переменной
• Когда и как использовать каждую переменную
• Соотношение между переменными (например, trace_id vs request_id)

3. Неясная семантика между trace_id, request_id, operation_id

Разработчики не понимают, куда помещать различные идентификаторы:

• span_id (уникальный для каждого вызова)
• request_id (сквозной идентификатор запроса)
• trace_id (идентификатор всей трассировки)

Предлагаемое решение

1. Исправить описание operation_id_cvar

Заменить текущее описание на ясное назначение:

operation_id_cvar: ContextVar[Optional[str]] = ContextVar("operation_id_cvar", default=None)
"""Уникальный ID операции (span_id) для трассировки отдельных вызовов"""

2. Добавить документацию по контекстным переменным

Создать документацию, объясняющую назначение каждой переменной:

Context Variable	Назначение	Когда использовать
trace_id_cvar	Уникальный ID всей бизнес-транзакции	Для сквозной трассировки всего запроса
request_id_cvar	Уникальный ID входящего запроса	Для идентификации конкретного запроса от клиента
operation_id_cvar	Уникальный ID отдельной операции (span)	Для каждого вызова к внешним системам
authorization_cvar	JWE токен авторизации	Для передачи учетных данных
session_id_cvar	ID пользовательской сессии	Для отслеживания сессии пользователя

4. Прояснить семантику идентификаторов

Четко определить:

• trace_id = сквозной идентификатор всей трассировки (как Correlation-ID)
• request_id = идентификатор входящего запроса (может совпадать с trace_id)
• operation_id = идентификатор отдельной операции (как Span-ID)

5. Добавить примеры использования

# Пример правильного использования
def setup_tracing_context(client_request_id: str):
    """Установка контекста для распределенной трассировки"""
    # Сквозные идентификаторы (не меняются)
    trace_id_cvar.set(client_request_id)  # или generate_trace_id()
    request_id_cvar.set(client_request_id)
    
    # Для каждого вызова - новый operation_id (span_id)
    operation_id_cvar.set(generate_span_id())

async def call_external_service():
    """Пример вызова внешнего сервиса"""
    # Генерируем новый span_id для этого вызова
    operation_id_cvar.set(generate_span_id())
    
    headers = {
        "X-Trace-ID": trace_id_cvar.get(),
        "X-Span-ID": operation_id_cvar.get(),
        "X-Request-ID": request_id_cvar.get()
    }
    # Вызов сервиса...

Ожидаемый результат

✅ Четкое понимание назначения каждой контекстной переменной
✅ Ясные guidelines по использованию для распределенной трассировки
✅ Устранение путаницы между trace_id, request_id, operation_id
✅ Возможность правильной реализации сквозной трассировки запросов