---

[I128-2818] Реализовать наблюдаемость Observability для промышленных модулей

---

НАЧАЛО >> Оглавление >> Общее описание >> История изменений >> Что нового в проекте I128 >> Версия 2026.3 >> [I128-2818] Реализовать наблюдаемость Observability для промышленных модулей📄 Скачать в DOCX

---

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

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

Завершено: 08.09.2026 13:40

1. Цель

Нужно реализовать общесистемный модуль Observability для ИРБИС 128. Модуль должен дать единый контракт публикации эксплуатационных сигналов, настройки metric profiles, routing policies, retention, dashboards и безопасных диагностических пакетов для промышленных модулей.

Observability должен быть владельцем нормализации, маршрутизации, агрегации, хранения краткоживущих технических сигналов, маскирования и диагностического представления эксплуатационных данных. Доменные модули должны публиковать только свои безопасные domain-specific signals и не должны сами решать, что писать в Stat, SiteStat, StatForms, Log или HealthCheck.

1. Контекст

В промышленном контуре ИРБИС 128 задачи, workflowпереходы, публичные формы, события, очереди, файловые операции, рабочие календари и интеграции должны диагностироваться одинаково. Сейчас при отсутствии общего контракта есть риск получить разрозненные частные логи, счетчики, healthпроверки и отчеты в каждом модуле.

Observability должен стать общим слоем между модулями-источниками и существующими системными механизмами: Stat, SiteStat, StatForms, Log, HealthCheck, EventBus, Queue, TraceContext и Security. Модуль не заменяет эти системы, а определяет, какие сигналы куда маршрутизируются, как агрегируются, сколько хранятся, какие данные маскируются и что может быть включено в диагностический пакет.

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

Нужно реализовать модель эксплуатационных сигналов:

• ObservabilitySignal: нормализованный сигнал от модуля с source module, operation, kind, result, severity, timestamp, duration, project key, workflow key, record type, record key, actor/principal, host/context, trace id, correlation id и idempotency key при наличии.
• Поддерживаемые типы сигналов: counter, gauge, timer, histogram, status, incident, logsignal и tracelink.
• Safe payload: сигнал не должен содержать текст записи, ответ, комментарий, содержимое вложения, скрытые поля, персональные данные, токены и секреты без явной policy.
• Fingerprint или idempotency key для повторяемых, фоновых и массовых операций.

Нужно реализовать profiles и routing:

• ObservabilityMetricProfile: включенные группы сигналов, dimensions, sampling, aggregation, thresholds, retention и доступность просмотра.
• Назначение профиля на уровне системы, модуля, проекта, workflow, типа записи, публичной формы, API-поверхности или фоновой операции.
• ObservabilityRoutingPolicy: правила маршрутизации signal groups в Stat, SiteStat, StatForms, Log, HealthCheck, dashboards, export, diagnostic packages и будущие sinks.
• Возможность отправки одного сигнала в несколько sinks, например одновременно в агрегированную статистику, технический журнал и health snapshot.
• Диагностический режим explain routing, показывающий администратору, почему сигнал был отправлен или не отправлен в конкретный sink.
• JSON import/export, system definitions, защита системных profiles/policies от прямого редактирования и пользовательские копии для настройки.

Нужно реализовать хранение и агрегацию:

• ограниченный normalized raw buffer для краткоживущих raw technical signals с отдельным retention, sampling, masking и правами диагностики;
• отдельные retention policies для raw signals, metric snapshots, health snapshots, diagnostic packages и экспортируемых отчетов;
• metric snapshots по разрешенным dimensions без раскрытия скрытых полей и персональных данных;
• агрегаты duration как минимум через count, min, max, average и percentile buckets, если это поддерживается выбранным sink;
• группировку ошибок по module, operation, project, workflow, transition, status, API method, queue job type и severity;
• состояние длительных операций: last result, progress, started at, finished at, status и ссылка на diagnostic package.

Нужно реализовать безопасность и masking:

• маскирование должно применяться до записи в долгоживущий sink, до отображения dashboard и до экспорта diagnostic package;
• права должны проверяться через Security отдельно для dashboards, raw signals, diagnostic packages, export, редактирования profiles/routing/sinks и retention purge;
• пользовательские и публичные сообщения об ошибках должны оставаться безопасными, технические детали доступны только пользователям с правом диагностики;
• удаление raw technical data по retention не должно разрушать агрегированную статистику.

Нужно реализовать системные dashboards первого промышленного контура:

• общий обзор системы и текущих degraded states;
• состояние модулей и runtime-операций;
• Workflow: переходы, conditions, screen apply, post-functions, errors и latency;
• EventBus: publication, delivery, retry, dead-letter, outbox/inbox lag;
• Queue: job runtime, attempts, failures, dead-letter, worker state и scheduling lag;
• публичные каналы: intake, abuse/security incidents, safe error rate;
• Tasks: create/update/transition, SLA/queue signals, assignment, comments, attachments, notifications, public intake и migration;
• storage/retention: объем raw buffer, snapshots, diagnostic packages и cleanup results.

Нужно реализовать интеграции:

• Stat, SiteStat и StatForms получают только утвержденные агрегированные бизнес- и продуктовые метрики.
• Log получает технические log signals с trace id, severity, module, operation и безопасным context.
• HealthCheck получает health snapshots, thresholds, degraded states и ссылки на diagnostic packages.
• EventBus передает event id, delivery id, outbox/inbox state и dead-letter status для связи с observability.
• Queue передает job runtime, retry, dead-letter, duration, attempts и last error summary.
• TraceContext связывает dashboard, log, event, queue job, workflow transition и diagnostic package.
• Security принимает решения доступа, а Observability применяет masking и retention policy.

Нужно реализовать контракт для Tasks как первого промышленного потребителя:

• Tasks публикует сигналы создания задачи, изменения задачи, workflowперехода, отказа condition, применения экрана, ошибки postfunction, назначения, комментария, вложения, события, уведомления, API-вызова, фоновой операции, миграции и публичного приема.

• Сигналы Tasks включают task key, project key, workflow key, transition key, status key, task type, result, duration, actor/principal, host/context и trace id при наличии.

• Tasks хранит только ссылку на выбранный ObservabilityMetricProfile и taskspecific имена сигналов, но не собственную routingсхему в Stat, Log или HealthCheck.

• Dashboards задач строятся через Observability и WorkflowFilter, а не через частные счетчики внутри Tasks.

• Диагностический экспорт проекта задач формируется как ObservabilityDiagnosticPackage с безопасными ссылками на HealthCheck, Log, EventBus и Queue.

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

Observability владеет signal envelope, metric profiles, routing policies, retention policies, normalized raw buffer, metric snapshots, dashboards, diagnostic packages, masking before sink/export и объяснением routing.

Observability не должен владеть доменной моделью задач, workflowстатусами, event log, job runtime, постоянным файловым хранилищем, правами как таковыми, healthcheck orchestration, бизнесотчетами StatForms, BIвитринами, пользовательскими уведомлениями и внешними transport adapters.

Tasks и другие доменные модули публикуют свои domainspecific signals и выбирают profiles, но не должны писать напрямую в конкретные статистические или журнальные sinks, кроме явно оставленного legacyкода до миграции.

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

Доменный модуль может опубликовать ObservabilitySignal без знания конкретного sink.

Routing policy может отправить один сигнал в несколько sinks и объяснить, почему каждый sink был выбран или пропущен.

Raw buffer хранит только нормализованные и маскированные технические данные с ограниченным retention; доменный текст, содержимое вложений, скрытые поля, персональные данные и секреты не попадают в raw buffer и diagnostic package без явной policy.

Stat, SiteStat и StatForms получают только утвержденные агрегаты, а не сырые технические payload.

Log получает технические log signals с trace id и безопасным context.

HealthCheck получает current health snapshots, thresholds, degraded states и ссылки на diagnostic packages, но не становится хранилищем полной истории метрик.

Dashboards первого промышленного контура доступны для system overview, module/runtime health, Workflow, EventBus, Queue, public intake/security, Tasks и storage/retention.

Права просмотра dashboards, raw signals, diagnostic packages, export и настройки profiles/routing/sinks проверяются отдельно через Security.

Diagnostic package формируется с trace id, агрегатами, ссылками на логи, результатами HealthCheck, event/queue контекстом и маскированными деталями без раскрытия чувствительных данных.

Отсутствие доступного Stat или SiteStat не ломает публикацию технических signals в Log и HealthCheck, если routing policy это допускает.

Observability можно использовать не только для Tasks, но и для Workflow, EventBus, Queue, WorkCalendar, WorkflowBoard, WorkflowCalendar, публичных форм, transportмодулей и будущих recordbased модулей.

1. Проверки И Документация

Нужно подготовить TestA-сценарии для:

• публикации сигналов разных типов;
• routing одного сигнала в несколько sinks;
• explain routing;
• маскирования safe payload до записи, просмотра и экспорта;
• retention raw buffer, snapshots и diagnostic packages;
• прав на dashboards, raw signals, diagnostic packages, export и администрирование profiles;
• propagation trace id через UI/API, Workflow, EventBus, Queue, Log и diagnostic package;
• Tasks profile: create, update, transition, post-function error, attachment, notification, API, background job, migration и public intake;
• fallback, когда Stat или SiteStat недоступен, но Log и HealthCheck продолжают принимать технические signals;
• HealthCheck provider checks системных profiles, routing policies, sinks, retention и dashboards;
• JSON import/export и защиту системных definitions.

В Help должны быть подготовлены:

• руководство администратора по profiles, routing policies, sinks, dashboards, retention, diagnostic packages и безопасному export;
• руководство разработчика по публикации ObservabilitySignal, safe payload, trace id, idempotency и интеграции доменных модулей;
• эксплуатационный runbook по анализу сбоев, degraded states, dead-letter/queue diagnostics, росту raw buffer, очистке retention и сбору diagnostic package.

-

Куда смотреть

• modules/Observability/api.php - системный класс модуля, PHPDoc-контракт и только наследуемые системные методы ObjectModule.
• modules/Observability/__call/*.inc - основная реализация функций Observability: normalization, safe payload masking, routing/explain, publish, snapshots, diagnostic packages, retention dry-run и HealthCheck.
• modules/Observability/system/observability_definitions.json - системные profiles, routing policies, retention, dashboards и sinks первого промышленного контура.
• modules/Observability/Tests/Module.inc - TestA-проверка контракта Observability.
• modules/Observability/Help/*.md - Help-совместимая документация администратора, программиста и runbook.

Изменения по файлам

• Добавлен новый общесистемный модуль Observability без прямой доменной логики Tasks, Workflow, Queue, EventBus, Security или HealthCheck.
• Реализована публикация безопасных эксплуатационных сигналов через __call-функции, а не через большой api.php.
• Добавлены system JSON definitions для SYSTEMDEFAULT и TASKSDEFAULT profiles, routing в dashboard/stat/sitestat/statforms/log/healthcheck/diagnostic-package и retention первого контура.
• Добавлены агрегирование metric snapshot, explainable routing, safe diagnostic package и dry-run retention.
• Добавлены административные поля, краткий формат записи, HealthCheckDefinition, Help и TestA.
• Проверено: php l для файлов модуля, JSON parse, TestA saferead 12/12, TestA structural 29/29, git diff -cached -check.

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

1.1. 🔗 blocks: I128-2805

1.2. 🔗 blocks: I128-2817

1.3. 🔗 blocks: I128-2820

1.4. 🔗 blocks: I128-2821

1.5. 🔗 blocks: I128-2822

1.6. 🔗 blocks: I128-2824

1.7. 🔗 blocks: I128-2829

1.8. 🔗 blocks: I128-2830

1.9. 🔗 blocks: I128-2831

1.10. 🔗 blocks: I128-2832

1.11. 🔗 blocks: I128-2833

1.12. 🔗 blocks: I128-2834

1.13. 🔗 blocks: I128-2835

1.14. 🔗 blocks: I128-2836

1.15. 🔗 blocks: I128-2837

1.16. 🔗 blocks: I128-2838

1.17. 🔗 blocks: I128-2839

1.18. 🔗 blocks: I128-2840

1.19. 🔗 blocks: I128-2823

1.20. 🔗 blocks: I128-2793

1.21. 🔗 blocks: I128-2794

1.22. 🔗 blocks: I128-2795

1.23. 🔗 blocks: I128-2797

1.24. 🔗 blocks: I128-2798

1.25. 🔗 blocks: I128-2799