Отладка сложных багов: методика поиска причины

Если ошибка появляется только после релиза, затрагивает один процент запросов и исчезает при повторной попытке, просмотр последних строк кода почти бесполезен. Для такого бага нужна не интуиция, а цепочка доказательств: зафиксировать симптом, найти конкретный запрос, восстановить путь данных и проверить гипотезу на воспроизводимом сценарии. Ниже — методика для веб-сервисов с базой данных, кешем, фоновой очередью и несколькими экземплярами приложения. Она рассчитана на Git 2.40+ и системы, где доступны структурированные логи и трассировка OpenTelemetry Semantic Conventions 1.x; названия полей в вашей версии SDK могут отличаться.

Сначала отделите симптом от причины

Сообщение «пользователь получил 500» описывает симптом, но почти ничего не говорит о механизме сбоя. Причиной может быть тайм-аут базы, устаревшая запись в кеше, повторная доставка задания или несовместимый формат сообщения после деплоя.

Первый результат расследования должен выглядеть как проверяемое утверждение: «при запросе к эндпоинту заказа сервис получил версию схемы 3, а обработчик ожидает поле из версии 4». Такое утверждение можно подтвердить логом, трассировкой или минимальным тестом. Формулировка «сломалась интеграция» для расследования слишком расплывчата.

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

Рабочий цикл расследования

1. Зафиксируйте контракт сбоя. Запишите время с часовым поясом, окружение, версию приложения, маршрут или фоновую задачу, идентификатор запроса, входные параметры без персональных данных и фактический результат. Добавьте частоту: ошибка возникает всегда, только при повторной отправке или, например, после простоя воркера. Проверка: другой инженер может повторить сценарий по записи, не задавая пять уточняющих вопросов.
2. Соберите один полный путь запроса. Найдите одну трассировку от входящего HTTP-запроса до SQL, обращения к внешнему сервису и фоновой очереди. Сверьте временную шкалу: где запрос ждал, где был повтор, на каком участке изменился идентификатор пользователя или заказа. Проверка: у вас есть одна связная цепочка событий, а не набор логов, найденных по приблизительному времени.
3. Разделите слой, где проявился сбой, и слой, где он возник. Ошибка на странице может быть вызвана API, API — очередью, а очередь — данными, записанными старой версией приложения. Проверьте последовательно клиент, балансировщик, приложение, кеш, базу и внешние зависимости. Проверка: хотя бы один слой исключён наблюдением: например, база возвращает корректную строку, но приложение теряет поле при преобразовании.
4. Сформулируйте несколько гипотез. Для каждой укажите предсказание и способ проверки. Гипотеза «сломался кеш» должна превращаться в проверку: при обходе кеша ошибка исчезает, а значение из базы соответствует ожидаемому. Не меняйте сразу пять настроек — иначе результат эксперимента нельзя будет интерпретировать. Проверка: у каждой гипотезы есть результат «подтверждено», «опровергнуто» или «недостаточно данных».
5. Сделайте минимальное воспроизведение. Уберите лишние параметры, пользователей и шаги, но сохраните условие, при котором возникает ошибка: конкретную версию записи, порядок событий или задержку. Если баг связан с данными, используйте обезличенный снимок. Проверка: сценарий запускается несколько раз и сохраняет тот же характер сбоя.
6. Проверьте исправление на границе, а не только на счастливом пути. Для проблемы с повторной доставкой задания проверьте один запуск, два одинаковых запуска и запуск после частичного ответа внешнего сервиса. Для миграции — старый и новый формат данных. Проверка: исправление устраняет первопричину и не маскирует ошибку дополнительным ретраем.
7. Зафиксируйте причинную цепочку. В задаче или постмортеме запишите три вещи: что наблюдали, какой эксперимент исключил альтернативы и какое изменение устраняет механизм сбоя. Проверка: человек, который не участвовал в расследовании, понимает, почему выбран именно этот фикс.

Как выбирать способ локализации

У сложного бага редко бывает один универсальный инструмент. Логи быстрее всего отвечают на вопрос «что произошло», трассировка — «где прошло время», а бинарный поиск по изменениям — «какое изменение изменило поведение». Сравнивайте не инструменты сами по себе, а стоимость доказательства конкретной гипотезы.

Если проблема затрагивает один HTTP-запрос, начните с логов и минимального сценария. Если путь проходит через несколько сервисов, сначала восстановите trace ID и временную шкалу. Если баг появился сразу после серии изменений, а окружение стабильно, используйте бинарный поиск по коммитам. Это не взаимозаменяемые методы: трассировка может показать место задержки, но не обязательно объяснит, почему данные оказались неверными.

Что ломается первым

Нет единого идентификатора

Логи веб-сервера, приложения и воркера оказываются бесполезными, если в каждом используется свой идентификатор. Передавайте один request ID или trace context через границы сервисов и сохраняйте его в каждом событии. Идентификатор не должен содержать email, телефон или другой пользовательский атрибут.

Ретрай скрывает первичную ошибку

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

Идемпотентность [1] — свойство операции, при котором повторное выполнение с теми же входными данными не создаёт новый побочный эффект. Например, повторная установка статуса заказа в «оплачен» не должна повторно списывать деньги.

Логи есть, но полезного контекста нет

Сообщение «database error» не заменяет имя операции, тип запроса, длительность и безопасный идентификатор записи. При этом не записывайте целиком токены, пароли, платёжные реквизиты и содержимое пользовательских запросов. Перед отправкой данных в систему логирования задайте список разрешённых полей, а не маскируйте всё постфактум.

Тест проходит только на локальной машине

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

Как измерять, если цифр пока нет

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

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

Когда подход не сработает

• Ошибка не воспроизводится. Сначала увеличьте полноту наблюдений и собирайте только безопасные признаки запроса. Не включайте отладочный режим в проде без ограничения доступа и контроля объёма данных.
• Данных слишком много. Оставьте выборочную трассировку для обычных запросов и временно повысьте детализацию для узкого сценария. Изменение должно иметь срок отключения и владельца.
• Коммит не находится. Проверьте миграции, конфигурацию и внешние зависимости: поведение могло измениться без изменения репозитория.
• Фикс убрал симптом, но не причину. Спросите, что произойдёт при повторе, тайм-ауте, старой записи или падении соседнего сервиса. Если ответ неизвестен, расследование ещё не закончено.

Что делать дальше

Начните с одного сервиса и добавьте обязательный минимум: структурированный лог с уровнем, временем, версией приложения и trace ID; измерение длительности внешних вызовов; отдельный счётчик повторов и ошибок; ссылку из инцидента на конкретный сценарий воспроизведения. Затем возьмите последний сложный баг и перепишите его историю в формате «симптом — гипотеза — эксперимент — результат — исправление». Следующим показателем для продакшена выберите не только количество 500, но и долю запросов, для которых нельзя восстановить полный путь от входа до ответа.