---

[I128-2793] Ввести TraceContext для сквозной трассировки операций

---

НАЧАЛО >> Оглавление >> Общее описание >> История изменений >> Что нового в проекте I128 >> Версия 2026.3 >> [I128-2793] Ввести TraceContext для сквозной трассировки операций📄 Скачать в DOCX

---

Тип	Версия	Статус	Приоритет	Исполнитель
⚙️ Новые возможности	2026.3	🔘 Завершено	Средний	Ilya Mikhaylenko

Компоненты: Нет

Завершено: 08.09.2026 12:28

1. Цель Ввести общесистемный контракт TraceContext для сквозной трассировки операций в ИРБИС 128: один trace id должен проходить через UI, API, workflow-переход, событие, фоновое задание, транспорт, лог, HealthCheck и TestA evidence.

2. Контекст TraceContext не является отдельным журналом событий, audit-хранилищем, очередью или доменным модулем. Это легкий платформенный механизм, который позволяет разным модулям связать свои собственные записи диагностики вокруг одной пользовательской или системной операции.

3. Что Нужно Сделать

• Реализовать создание нового trace id для пользовательских действий, API-вызовов, фоновых операций и системных задач.

• Реализовать прием существующего trace id из безопасных источников: HTTP-заголовок, параметр внутреннего API, Queue job, EventBus event, CLI/CI/TestA context.

• Реализовать нормализацию и валидацию trace id: формат должен быть стабильным, коротким для логов, безопасным и не содержать персональные данные, секреты или предметную семантику.

• Реализовать propagation trace id через основные runtimeграницы: controller/action, ObjectModule, workflow transition, postfunction, EventBus publication, Queue job, transport delivery, file operation, log entry, HealthCheck run и TestA report.

• Ввести DTO или сервис TraceContext с понятным API: получить текущий trace id, создать child/scope, передать в downstream operation, сериализовать в безопасный diagnostic payload.

• Ввести provider-контракт TraceDiagnosticProvider: модуль может вернуть безопасный диагностический срез по trace id, не раскрывая скрытые поля и секреты.

• Реализовать fallback для legacy-кода: если trace id отсутствует, система создает новый или помечает диагностический срез как untraced без падения пользовательского действия.

• Реализовать masking/redaction для вывода trace diagnostics.

• Подготовить базовую интеграцию с логами и диагностическими отчетами, чтобы администратор мог искать ошибку по trace id.

  1. Границы Ответственности

• TraceContext не должен хранить постоянную доменную историю операций.

• TraceContext не должен заменять 907, EventBus, Queue, Security audit или системные логи.

• Предметные модули сами решают, какие безопасные diagnostic slices они могут отдать по trace id.

  1. Критерии Приемки

• Одно действие пользователя получает trace id и этот id виден во всех связанных runtime-артефактах, которые поддерживают TraceContext.

• Повторное выполнение job или delivery attempt сохраняет исходный trace id и при необходимости добавляет внутренний attempt/scope id.

• По trace id можно получить безопасный диагностический отчет без персональных данных, секретов и скрытых полей.

• Отсутствие trace id в legacy-вызове не ломает выполнение.

• TraceContext может использоваться в TestA как evidence key для сквозных сценариев.

  1. Проверки И Документация Нужно подготовить TestA-сценарии для создания trace id, приема внешнего trace id, propagation через workflow/EventBus/Queue, fallback, masking и диагностического поиска. В Help для разработчиков нужно описать API TraceContext, правила передачи и ограничения безопасности.

-

Реализован первый срез TraceContext как общесистемного контракта сквозной трассировки.

Что входит:

• новый модуль TraceContext без доменной логики Tasks/Workflow; он создает, нормализует и переносит trace id;
• контекст запроса и scope id для вложенных операций;
• прием входящего trace id только из доверенного carrier, иначе входящее значение сохраняется как external correlation id;
• diagnostic provider registry и безопасный TraceDiagnosticReport;
• автоматическая инициализация HTTPrequest context и response header XI128TraceId;
• добавление trace id в Log::Write без автозагрузки TraceContext из Log;
• Helpстраницы и TestAсценарий модуля.

Проверки:

• php -l для initsystem.php, modules/Log/api.php и всех файлов modules/TraceContext;
• git diff --check;
• TestA HTTP: module=TraceContext, total=10, passed=10, failed=0;
• ручная HTTPпроверка: irbis128.local возвращает заголовок XI128TraceId.

1. Связанные задачи

1.1. 🔗 blocks: I128-2794

1.2. 🔗 blocks: I128-2795

1.3. 🔗 blocks: I128-2796

1.4. 🔗 blocks: I128-2798

1.5. 🔗 blocks: I128-2805

1.6. 🔗 blocks: I128-2806

1.7. 🔗 blocks: I128-2807

1.8. 🔗 blocks: I128-2808

1.9. 🔗 blocks: I128-2809

1.10. 🔗 blocks: I128-2810

1.11. 🔗 blocks: I128-2811

1.12. 🔗 blocks: I128-2817

1.13. 🔗 blocks: I128-2818

1.14. 🔗 blocks: I128-2820

1.15. 🔗 blocks: I128-2821

1.16. 🔗 blocks: I128-2822

1.17. 🔗 blocks: I128-2824

1.18. 🔗 blocks: I128-2827

1.19. 🔗 blocks: I128-2830

1.20. 🔗 blocks: I128-2831

1.21. 🔗 blocks: I128-2832

1.22. 🔗 blocks: I128-2833

1.23. 🔗 blocks: I128-2834

1.24. 🔗 blocks: I128-2835

1.25. 🔗 blocks: I128-2836

1.26. 🔗 blocks: I128-2837

1.27. 🔗 blocks: I128-2838

1.28. 🔗 blocks: I128-2839

1.29. 🔗 blocks: I128-2840

1.30. 🔗 relates to: I128-2792