Эксплуатация и OpenTelemetry
Elang предоставляет закрытые эксплуатационные сводки и необязательные ручные трассировки OpenTelemetry. Экран эксплуатации показывает состояние очереди, метаданные неудачных заданий, накопление SQL-outbox, сигналы активности обработчиков и агрегаты HTTP за час. Он не раскрывает тела заданий, cookie, bearer-токены, значения SQL или адреса электронной почты пользователей.
Подготовка и включение эксплуатационного мониторинга
php elang platform:setup
OPERATIONS_ENABLED=true
$app->provider(new Elang\Observability\Provider());
Откройте /operations под подтверждённой учётной записью администратора, сменившего временный пароль на постоянный. /operations/metrics возвращает ту же закрытую сводку JSON с теми же проверками учётной записи и роли. Повторный запуск неудачных заданий выполняется через формы POST, защищённые CSRF. Роли, переданные браузером, никогда не предоставляют доступ. Не делайте этот эндпоинт публичным и не рассматривайте его агрегированный JSON как публичную проверку работоспособности.
Метрики HTTP используют имена маршрутов вместо необработанных путей URL и строк запросов. Они хранят число запросов, число серверных ошибок, суммарную и максимальную длительность в минутных интервалах. Экран вычисляет среднюю задержку. Эти значения не являются процентилями, и их нельзя представлять как p95/p99. Если хранилище мониторинга даёт сбой, обработка запросов продолжается; отдельно оповещайте об отсутствии телеметрии.
Обработчики очереди и outbox сообщают случайный идентификатор процесса, тип, время последнего сигнала активности и число обработанных попыток. Сигнал старше 120 секунд помечается устаревшим. Долгое задание может обоснованно превысить этот интервал, поэтому используйте политики сигналов активности и резервирования, подходящие нагрузке. Пустой список обработчиков не доказывает, что процесс остановлен; проверьте диспетчер процессов и конфигурацию мониторинга.
php elang queue:work --max-jobs=1000
php elang outbox:work
php elang operations:prune
Запускайте очистку из контролируемого планировщика. Она сохраняет агрегаты HTTP в течение 24 часов, метаданные обработчиков — семи дней, а опубликованные строки outbox — семи дней. Неопубликованные строки сохраняются. Для бизнес-записей аудита и неудачных заданий принимаются отдельные решения о сроках хранения.
Включение трассировок
OTEL_ENABLED=true
OTEL_SERVICE_NAME=orders-api
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:4318/v1/traces
OTEL_SAMPLE_RATE=0.1
Фреймворк использует поддерживаемый OpenTelemetry PHP SDK и экспортёр OTLP HTTP/protobuf. Для этих ручных участков трассировки не требуется нативное расширение OpenTelemetry. Локальный Collector рекомендуется как граница экспорта; для удалённого сбора используйте HTTPS. Пользовательский экспорт по HTTP ограничен loopback-адресами или именем хоста сборщика разработки. Защитите сборщик, его учётные данные для последующих систем и доступ к хранилищу трассировок.
Серверные участки трассировки HTTP содержат метод, имя маршрута и статус ответа. Участки потребителя очереди содержат зарегистрированное имя задания и передают контекст трассировки W3C от момента отправки. Тело или строка запроса, заголовок авторизации, исходный параметр пути, адрес почты, параметр SQL или сообщение исключения намеренно не прикрепляются. Для этой базовой реализации достаточно классов ошибок и статуса. Проверяйте каждый собственный атрибут трассировки перед добавлением чувствительных значений или идентификаторов с высокой кардинальностью.
Выборка корневых трассировок по умолчанию составляет 10%; действительный родительский контекст влияет на выборку, учитывающую родителя. Публичные клиенты могут передавать заголовки трассировки, поэтому не используйте их для авторизации и при необходимости отбрасывайте недоверенный входящий контекст на границе инфраструктуры. Задания сохраняют только контекст трассировки отдельно от бизнес-данных.
Экспорт использует ограниченный тайм-аут транспорта 250 мс без повторных попыток. Пакетная обработка всё равно может выполнять экспорт во время запроса, принудительной отправки или завершения; это не отдельный фоновый поток и не гарантия нулевой задержки. Держите сборщик рядом. Сбой экспорта не должен раскрывать секреты или нарушать бизнес-поведение. Долгоживущие процессы должны принудительно отправлять данные в контролируемых точках жизненного цикла и перезапускаться под управлением диспетчера.
Реагирование на эксплуатационные проблемы
- Растёт число ожидающих заданий: проверьте процесс обработчика, регистрации, доступные ресурсы базы данных и длительность резервирования.
- Растёт число неудачных заданий: изучите классы исключений и идемпотентность приложения перед повтором.
- Растёт число записей outbox: восстановите соединение Redis и процесса пересылки; сохраните неопубликованные строки.
- Отсутствуют метрики HTTP: проверьте
OPERATIONS_ENABLED, подготовку таблиц и трафик маршрутов приложения. - Отсутствуют трассировки: проверьте эндпоинт, протокол сборщика, выборку, сетевую политику и зависимости экспортёра.
- Обработчики устарели: проверьте историю завершений и перезапусков процессов и не блокирует ли задание выполнение дольше ожидаемого интервала активности.
Резервные копии, независимые проверки доступности, маршрутизация оповещений, аварийное восстановление и метрики хостов базы данных, Redis и S3 относятся к развёртыванию. Исправная панель фреймворка не может доказать, что резервные копии восстанавливаются или внешние провайдеры работают. См. развёртывание и тестирование.