И почему и когда нельзя

Несколько месяцев назад я читал о кодах состояния HTTP - как обычно бывает - когда наткнулся на 2 жемчужины:

  1. Код возврата 418: «Я ЧАЙНИК». Это первоапрельская шутка - ну, насколько мы, ботаники, можем понять. В конце статьи будет ссылка.
  2. Ответы 4xx предназначены для отказов, вызванных клиентом, а ответы 5xx - для отказов, вызванных сервером. Это разные.

Я знал это в глубине души, но только когда я работал над конкретным проектом, я не осознал мудрость, стоящую за этим различием, и почему это важно. Обработка ошибок - разница между разработкой и проектированием - требует понимания роли, которую все участники играют в системе. Различные причины ошибок требуют различного обращения, которое включает в себя регистрацию предупреждений и ошибок.

Если вы прочитали «Прекратите использовать console.log!» статей, тогда воспринимайте это как шаг 2. В разработке дело не в знании того, что методы существуют - IDE делают это за вас, - дело в знании того, когда их использовать.

Какие актеры входят в вашу систему?

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

Производители отправляют события в мою систему. Разработчики работают над тем же продуктом, что и я.

Вызывающие API - это сторонние приложения (HTTP-клиенты), написанные другими компаниями, которые расширяют мой продукт. Запрос к моему API запускается пользователем в своем приложении во время настройки. Разработчики работают над разными продуктами, наверное, другими компаниями, чем я.

Получатели - это серверы, которые получают HTTP-запросы от моей системы всякий раз, когда я слышу о событии от производителя. В этой ситуации моя система является HTTP-клиентом, а их - HTTP-сервером. Те же люди, у которых есть API Caller, владеют приемником.

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

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

Давайте рассмотрим некоторые ошибки, чтобы проиллюстрировать правильную обработку ошибок.

У вызывающего API отсутствует параметр

Сообщая моей системе, что сторонняя сторона хочет получать события, вызывающий API забыл включить URL-адрес моей системы в события POST. Это ошибка вызывающего API. Как и следовало ожидать, мы отправляем обратно ошибку 400.

Мы должны войти? Да, благодаря поддержке. Вызывающий API может попытаться диагностировать эту ошибку 400 и может обратиться за помощью в службу поддержки. В этом случае журнал может содержать дополнительную информацию. (По соображениям безопасности старайтесь избегать отправки трассировок стека обратно клиентам в ответах API, поскольку корреляция номеров строк может выдавать версии пакетов третьим сторонам и, таким образом, открывать уязвимости в вашей системе)

Поскольку поддержка - это основная причина, по которой мы хотим регистрироваться, мы должны регистрироваться в «info».

Дополнительное примечание: почему уровни журнала имеют значение?

Вы можете - и хотите - настроить свое приложение так, чтобы по-разному обрабатывать разные уровни журналов. Например, мы отключаем журналы отладки вне сред разработки, что очень помогает с соответствием PII. У нас также есть система, которая просматривает операторов (например, просыпается по телефону в 3 часа ночи) , если в журналах есть несколько «ошибок». выходят, или если приходит много журналов «предупреждений», так что проблемы могут быть решены.

Боковое примечание: как получить разные уровни журнала?

В Python загляните в основной пакет logging; в Java - SLF4J (или что-то еще, что сейчас модно - в Java слишком много пакетов журналирования, моя автозаполнение IDE так запутано); в Node вы можете «обезбавить» объект консоли. Вы также можете использовать пакет, хотя другие используемые вами пакеты могут не соответствовать пакету ведения журнала.

Ошибка запроса вызывающего API: невозможно получить доступ к базе данных

Что-то не так и исправить могут только операторы. Мы хотим, чтобы они действовали как можно скорее, чтобы восстановить доступность, даже если сейчас 3 часа ночи. Их нужно перелистывать.

В этом сценарии мы регистрируем ошибку.

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

Производитель отправил недопустимое событие

Это сложно. Это ошибка нашего продукта, но не моей команды.

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

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

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

Ошибка при отправке депеши получателю

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

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

Вывод

То, что это ошибка, не означает, что это ваша ошибка. Ведение журнала на соответствующем уровне во время обработки ошибок касается решения проблем, связанных с поддержкой, операциями, соответствием и системным интерфейсом. Не только console.log и не только console.info, console.error и т. Д .; войдите на нужный уровень по правильной причине.

Как и обещал: «Я чайник»