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

Error updating captured_at for purchase 1244

захваченный_у кого? Что было захвачено? Какое влияние это оказывает на клиентов? И было ли это действительно настолько важным, чтобы проснуться посреди ночи?

В мире профессиональной разработки программного обеспечения то, как ваше приложение терпит неудачу, так же важно, как и то, как оно достигает успеха. Неважно, имеет ли ваше приложение 99% покрытие тестами, внешний интерфейс AngularJS, Clojure под капотом и жонглирует данными между тремя разными базами данных NoSQL одной рукой, связанной за спиной — если процесс покупки нарушен и вы не можете расшифровать java.lang.ClassCastException, смотрящее вам в лицо, то вы в опасности. проблема.

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

Вот некоторые моменты, которые следует учитывать при написании сообщений об ошибках, чтобы гарантировать, что если что-то пойдет не так, вы сможете быстро отследить проблему.

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

Будьте описательными

При написании кода в сжатые сроки легко облениться с сообщениями об ошибках:

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

Теперь я могу видеть, кто пытался обновить captured_at (задачу rake), а также когда и почему это не удалось.

Всегда регистрировать обратные трассировки

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

По возможности опишите воздействие на систему

В команде из 4–5 разработчиков и более невозможно уследить за всеми фичами, добавляемыми в продукт. Если вас разбудит посреди ночи сообщение об ошибке, приведенное выше, если только вы не написали его, вы, вероятно, не полностью поймете его влияние на систему.

Означает ли это, что клиенты видят страницы с ошибками? Действительно ли здесь захватываются средства, но заказы не выполняются? Это что-то, что может подождать до завтрашнего утра?

Будьте великодушны к человеку, который с затуманенными глазами смотрит на это сообщение в 2 часа ночи, пытаясь понять его. Если возможно, опишите влияние ошибки в самом сообщении:

Это действительно лишняя миля, и будет очень признателен всем, кто должен отладить эту ошибку.

Предлагайте указатели для отладки

Мы все видели это предупреждение от Rails в какой-то момент:

Called id for nil, which would mistakenly be 4 — if you really
wanted the id of nil, use object_id

В противном случае вызов id на nil мог бы стать источником чрезвычайно неприятных ошибок, если бы не рука помощи (теперь устаревшая) whiny_nil. То же самое относится и к сообщениям об ошибках, которые вы пишете. По возможности дайте человеку, отлаживающему ваше сообщение об ошибке, преимущество:

Сделайте ошибки видимыми

После этих нескольких настроек у вас теперь есть что-то очень полезное. Осталась еще одна проблема с вашим сообщением об ошибке: разработчики его не увидят. Если вы хотите привлечь внимание разработчика, вам понадобится нечто большее, чем просто Rails.logger. Вы также захотите уведомить службу мониторинга ошибок, такую ​​​​как Honeybadger или Airbrake, чтобы вы получали электронное письмо (или SMS, IM и т. Д.), Как только произойдет ошибка.

Настроить Honeybadger, например, очень просто. И как только вы это сделаете, он будет автоматически получать уведомления обо всех исключениях, которые вы явно не обрабатываете в коде своего приложения Rails.

Для исключений, которые вы обрабатываете, как в нашем предыдущем примере, их также легко отправить в Honeybadger:

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

Резюме

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

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