Проблема web-диагностики обычно начинается с одного наблюдения: страница вернула 502, форма осталась пустой или запрос получил отказ. Инженер сразу называет виновный слой — базу, прокси или браузер — и начинает менять его. Цена такого прыжка измеряется не только временем. Случайный фикс убирает исходный сигнал, добавляет новый побочный эффект и оставляет следующему человеку только фразу «после изменения стало лучше».
Надёжный разбор начинается с конверта симптома. В нём есть метод, путь, статус, время, размер ответа, идентификатор запроса и граница, на которой запись получена. Эти поля не отвечают на вопрос «кто виноват». Они отвечают на более узкий вопрос: какой следующий сигнал отличит два правдоподобных объяснения. Такой порядок экономит часы: сначала уменьшаем пространство поиска, затем открываем конкретный лог или трассу.
Симптом не равен причине
Статус HTTP описывает результат обмена на конкретной границе. 502 говорит клиенту, что шлюз получил недействительный ответ от upstream; он не говорит, почему upstream ответил так. Это может быть разрыв соединения, таймаут, ошибка маршрута или повреждённый ответ. Если в карточке инцидента оставить только «сервер упал», диагностика уже потеряла важное различие. В карточке должны соседствовать исходный статус и место, где он увиден.
То же относится к пустому экрану. Пустой HTML, ответ API с пустым массивом и ошибка рендера дают похожую картинку, но требуют разных проверок. Поэтому полезно сначала классифицировать внешний симптом, а не выбирать инструмент по привычке. Ниже показана маленькая функция для локального разбора учебного набора. Она не делает сетевых запросов: её задача — привести вход к следующему наблюдаемому шагу.
| Поле | Пример | Что позволяет проверить | Чего не доказывает |
|---|---|---|---|
| Метод и путь | GET /checkout | какая операция повторяется | что именно сломано внутри |
| Статус | 502 | на какой границе возник отказ | причину ответа upstream |
| Идентификатор | traceparent или request-id | связать записи разных слоёв | полноту цепочки |
| Время и длительность | 12:04:18, 4.2 с | найти окно в журнале | что задержка была единственной причиной |
| Тело и заголовки | empty, content-type | отличить данные от рендера | что пользователь увидел именно этот текст |
Учебный локальный классификатор
Функция принимает только наблюдаемую форму ответа: статус, заголовки и тело. Для 502/504 она проверяет наличие traceparent или x-request-id и предлагает сопоставить gateway с upstream. Для 401/403 ведёт к аутентификации и политике доступа. Для 200 с пустым содержимым разделяет данные и DOM. Входы намеренно маленькие: так видно, какое поле повлияло на выбор.
import { classifyWebSymptom } from './upgrade-2027-01.mjs';
const samples = [
{ status: 502, headers: { traceparent: '00-abc-123-01' }, body: 'Bad Gateway' },
{ status: 200, headers: { 'content-type': 'text/html' }, body: '<main>empty</main>' },
];
for (const sample of samples) console.log(classifyWebSymptom(sample));
// gateway-failure -> сопоставить gateway и upstream по идентификатору
// rendering-or-data-failure -> разделить пустой ответ API и пустой DOMОжидаемый результат — два разных маршрута, а не общий совет «посмотреть логи». Первый маршрут требует найти одинаковый идентификатор на двух границах. Второй требует сравнить тело ответа с фактически построенным DOM. Если добавить к объекту лишнее поле, функция его не использует: это полезное напоминание, что необработанный контекст не превращается в доказательство автоматически.
Гипотеза должна иметь различающий сигнал
После классификации запишите две гипотезы в форме «если причина X, то при проверке Y увидим Z». Например: если gateway не получил ответ upstream, в access log будет 502, а в application log не будет записи с тем же request-id. Если приложение вернуло ошибку, обе записи появятся, но статусы и время будут различаться. Такая формулировка заставляет заранее назвать отрицательный результат. Без него любая найденная запись легко превращается в подтверждение первоначальной версии.
Идентификатор запроса здесь играет роль ключа соединения, а не печати достоверности. Он помогает собрать события, но не исключает потерю записи, повторную отправку или ошибку генератора идентификатора. Временное окно тоже не заменяет ключ: два запроса могут идти одновременно, а часы на разных узлах могут расходиться. Если ключ отсутствует, это отдельный результат диагностики, а не разрешение подставить ближайшую запись.
Действия по порядку
- Сохранить метод, путь, статус, время, длительность, размер ответа и идентификатор на внешней границе.
- Сформулировать две причины и для каждой назвать сигнал, который даст разные результаты.
- Проверить access log и журнал следующего слоя в одном временном окне; не смешивать записи только по похожему пути.
- Сопоставить идентификатор, parent/child-контекст и направление запроса; отдельно отметить пропущенные записи.
- Внести изменение только после того, как найден слой и повторяемый признак; после изменения повторить тот же запрос.
Ограничения и следующий шаг
Классификатор не устанавливает root cause и не заменяет расследование. Прокси может изменить статус, middleware — скрыть исходное тело, а sampled trace — не содержать нужного span. Для асинхронной очереди одного request-id тоже мало: понадобится связать producer, сообщение и consumer отдельными полями. В production нельзя выводить причину из одного совпадения времени или одного удачного повтора.
Следующий практический шаг — добавить в ваш журнал структурированные поля request_id, trace_id, route, status и duration_ms, а затем проверить один отказ по маршруту выше. Критерий готовности простой: другой инженер по конверту симптома понимает, какой запрос искать, где искать и какое наблюдение изменит решение.
Проверяемые источники
- RFC 9110: HTTP Semantics — версия и дата: Internet Standard, June 2022, DOI 10.17487/RFC9110. Применение: Определение семантики статусов 502, 504, 401 и 403. Граница: RFC описывает HTTP-обмен, но не знает топологию конкретного приложения и не устанавливает его причину отказа.
- Trace Context — W3C Recommendation — версия и дата: Recommendation, 23 November 2021. Применение: Правила полей traceparent и переноса контекста между HTTP-границами. Граница: Стандарт помогает связать контекст, но не гарантирует, что каждый сервис записал span или что связь доказывает причинность.
- NIST SP 800-92: Guide to Computer Security Log Management — версия и дата: September 2006, DOI 10.6028/NIST.SP.800-92. Применение: Практика управления журналами: содержимое, время, источник и пригодность записи для анализа. Граница: Руководство не является журналом приложения и не даёт данных о конкретном инциденте.