Диагностика, которая ведёт от симптома к следующему действию

Пользователь сообщает: «агент не отвечает». За этой фразой могут стоять остановленная служба, недоступная база, неверный маршрут, истёкший ключ канала или внешний лимит. Интерфейс с одной красной лампой заставляет дежурного гадать. Полезный операционный UX разделяет состояния и показывает наблюдаемый факт, а не предполагаемую причину.

В AiHummer есть несколько уровней сигнала: состояние systemd-службы, /healthz, /readyz, команды aihummer status и aihummer doctor, журнал и коды ошибок. Они отвечают на разные вопросы. Хорошая инструкция дежурного связывает их последовательностью и заканчивается проверкой восстановления.

Status: обзор, а не приговор

Команда status показывает установку, службы и готовность шлюза. Если systemctl недоступен, честный результат — «состояние неизвестно», а не «компонент не установлен». Неизвестность требует дополнительной проверки; она не доказывает ни успех, ни отказ.

Смотрите, какой именно компонент отмечен. Шлюз может работать, а дополнительный сервис — отсутствовать. Если сценарий не использует речь или браузер, это одно влияние; если использует — другое. Статус оценивают относительно заявленного пользовательского пути.

Doctor: проблемы и предупреждения

Doctor выдаёт три класса результата: всё в порядке, работа с предупреждениями и обнаруженные проблемы. Некоторые проверки Node.js или материала регистрации могут быть предупреждениями, а не отказом шлюза. В инструкции дежурного укажите, какие предупреждения блокируют именно ваш запуск и кому они назначаются.

Не превращайте предупреждение в вечный фон. Если оно ожидаемо, запишите причину и дату пересмотра. Если неожиданно — создайте задачу. Сотня игнорируемых жёлтых строк скрывает новый сигнал так же эффективно, как общая красная ошибка.

Здоровье процесса и готовность

/healthz подтверждает живой процесс и возвращает версию. /readyz агрегирует настроенные проверки обязательных зависимостей и отвечает 503, когда одна из них не готова. Конкретный набор зависит от конфигурации, поэтому нельзя трактовать пробу как проверку только PostgreSQL. Балансировщик должен смотреть на готовность, иначе трафик продолжит идти в живой, но неработоспособный процесс.

Проверяйте пробы локально и через внешний маршрут. Разница указывает на прокси, TLS, DNS или сетевую политику. Сохраните время, код ответа и версию, но не полные заголовки авторизации.

Порядок от простого к предметному

Начните со службы: запущена ли она. Затем проверьте слушающий порт, /healthz, /readyz и последние строки журнала. Только после этого переходите к зависимости сценария: конкретному каналу, os-client, модели или внешнему API. Такой порядок сокращает область поиска и сохраняет факты до перезапуска.

Перезапуск без диагностики иногда временно помогает, но стирает контекст и маскирует повторяющуюся причину. Перед ним сохраните идентификатор корреляции, код ошибки, состояние проб и релевантный фрагмент журнала. Не копируйте секреты или полные персональные данные в тикет.

Как выглядит полезная ошибка

Сообщение содержит компонент, наблюдаемый факт, безопасное следующее действие и код для поиска. «Не удалось подключиться к PostgreSQL; /readyz вернул 503; проверьте соединение с базой» полезнее «внутренняя ошибка». Для пользователя формулировка остаётся человеческой, а для поддержки рядом есть стабильный код.

Различайте «не настроено», «нет прав», «недоступно по тарифу», «временно недоступно» и «состояние неизвестно». Это разные действия. Обобщение до одного слова заставляет человека менять настройки наугад и иногда расширять доступ без необходимости.

Моделируемый сценарий учебного инцидента

На тестовом контуре остановите базу. Убедитесь, что /healthz и /readyz расходятся ожидаемым образом, status и doctor показывают понятный результат, а журнал содержит идентификатор корреляции. Восстановите базу и подтвердите готовность. Затем остановите необязательный модуль и сравните сигнал: шлюз не должен выглядеть полностью упавшим, если функция не входит в сценарий.

Запишите фактическое время обнаружения и восстановления как результат упражнения, но не превращайте его в гарантию будущего ответа или времени доступности. Цель — найти неясные шаги, отсутствующие права и лишние перезапуски.

Таблица «сигнал — действие»

Составьте её до инцидента. /readyz с кодом 503 ведёт к просмотру результатов настроенных проб; 401 — к учётным данным и сроку их действия; 403 — к правам; 402 — к тарифному праву; 429 — к бюджету или частотному ограничению. Это стартовые направления, а не автоматический диагноз. Причину подтверждают журналом и состоянием зависимости.

Для канала добавьте внешний идентификатор попытки и ответ провайдера. Если сообщение поставлено в outbox, но не доставлено, интерфейс не должен показывать его как успешно полученное адресатом. Различайте «принято системой», «ожидает доставки», «доставлено» и «ошибка». Такая точность снижает опасные ручные повторы.

Логи должны быть достаточно подробными для связи событий и достаточно сдержанными для защиты данных. Маскируйте токены, пароли, QR и чувствительные тела. Ограничьте доступ и срок хранения. Копируя фрагмент в тикет, оставляйте время, компонент, код и идентификатор корреляции, но удаляйте лишний контекст.

Дашборд помогает увидеть тенденцию, однако не заменяет проверку конкретного запроса. Средняя задержка может быть нормальной, пока один канал полностью недоступен. Добавьте разрез по компоненту и классу ошибок, а для редкого сбоя храните трассу с известным идентификатором.

Новый дежурный проверяет инструкцию на практике. Дайте ему симптом и доступ к разрешённым инструментам, не подсказывая устно. Замерьте, на каком шаге инструкция двусмысленна, какой доступ отсутствует и где человек собирается сделать опасный перезапуск. Исправьте документ и повторите упражнение.

После инцидента обновите не только алерт, но и пользовательское сообщение. Если поддержка каждый раз переводит технический код вручную, знание должно перейти в интерфейс или справочник. При этом не перечисляйте внутренние адреса и архитектуру там, где сообщение увидит внешний пользователь.

Что должен увидеть пользователь

Снаружи не нужен полный стек. Пользователю важно понять, принято ли сообщение, требуется ли повтор и куда обратиться. Внутри оператору нужны точный компонент, время и идентификатор. Разделите эти уровни: публичный текст остаётся спокойным, техническая карточка даёт доказательства без секретов.

Проверьте локализацию каждого действия. Кнопка «Повторить» подходит только для безопасного повтора; при 403 нужна заявка на доступ, при 402 — проверка тарифа, при истёкшем QR — новый код. Точный следующий шаг — часть корректности, а не декоративная подсказка.

После исправления повторите исходный симптом на том же тестовом пути и сохраните подтверждение восстановления. Только затем закрывайте инцидент.

Команды перечислены в справочнике CLI, порядок проб — на странице systemd и проверки здоровья, значения кодов — в справочнике ошибок. Возьмите один недавний инцидент и проверьте, сможет ли новый дежурный пройти его по этим сигналам без устных подсказок.

После учения сравните хронологию глазами пользователя и дежурного. Первый должен понять судьбу своего сообщения, второй — найти компонент и безопасное действие. Если между этими представлениями есть пустой участок, добавьте статус или корреляцию, а не новый общий алерт. Повторите тот же отказ после правки инструкции.