Обработка ошибок
При использовании YDB SDK возникают ситуации, в которых необходимо обрабатывать ошибки.
Ошибки можно разделить на три категории:
- Временные сбои (retryable, далее R) — включают в себя кратковременную потерю сетевого соединения, временную недоступность или перегруженность одной из подсистем YDB, неспособность YDB ответить на запрос в течение установленного времени ожидания. В случае возникновения таких ошибок, повтор запроса, завершившегося с ошибкой, через некоторый промежуток времени с большой вероятностью будет выполнен успешно.
- Ошибки, которые не могут быть исправлены с помощью повтора (non retryable, далее N) — включают в себя некорректно сформированные запросы, внутренние ошибки YDB, запросы, несоответствующие схеме данных. В такой ситуации нет необходимости повторять запрос, требуется дополнительное вмешательство со стороны разработчика.
- Ошибки, которые, предположительно, могут быть исправлены с помощью повтора после реакции клиентского приложения (conditionally retryable, далее C) — включают в себя отсутствие ответа в течение отведенного времени, запрос аутентификации.
YDB SDK предоставляет встроенный механизм обработки временных сбоев. По умолчанию в SDK используется рекомендованная политика повторов, которую можно изменить в соответствии с требованиями клиентского приложения. YDB возвращает коды завершения, которые позволяют определить, уместна ли повторная попытка и какой выбрать интервал.
Операции следует повторять только в том случае, когда ошибки являются временными сбоями. Не пытайтесь выполнить повторно недопустимые операции, такие как вставка в таблицу строки с существующим значением первичного ключа или вставка данных несоответствующих схеме таблицы.
Крайне важно оптимизировать число повторных попыток и интервал между ними. Чрезмерное количество повторных попыток и слишком короткий интервал между ними создают избыточную нагрузку. Недостаточное количество повторных попыток не позволит завершить выполнение операции.
При выборе интервала обычно используются следующие стратегии:
- Экспоненциальная задержка. Для каждой последующей попытки интервал увеличивается по экспоненциальному закону.
- Интервалы с приращениями. Для каждой последующей попытки интервал увеличивается с определенными приращениями.
- Постоянные интервалы. Повторные попытки совершаются через одинаковые интервалы.
- Немедленный повтор. Повторные попытки совершаются немедленно.
- Случайный выбор. Повторные попытки совершаются через случайно выбранный интервал времени.
При выборе интервала и числа повторных попыток учитывайте статусы завершения YDB.
Не используйте бесконечные повторные попытки. Это может привести к возникновению избыточной нагрузки.
Не выполняйте немедленный повтор больше одного раза.
Журналирование ошибок
При использовании SDK рекомендуется записывать в журнал все ошибки и исключения:
- Журналируйте количество предпринимаемых повторных попыток. Увеличение числа регулярных повторных попыток часто указывает на наличие проблем.
- Журналируйте все ошибки, в том числе их типы, коды завершения и причины, вызывающие их появление.
- Журналируйте общее время выполнения операций, в том числе завершающихся после повторного выполнения.
Статусы завершения
Ниже приведены статусы завершения которые можно получить при работе с SDK.
Типы ошибок:
- R (retryable) — временные сбои
- N (non retryable) — ошибки, которые не могут быть исправлены с помощью повтора
- С (conditionally retryable) — ошибки, которые предположительно могут быть исправлены с помощью повтора после реакции клиентского приложения
| Статус | Описание | Реакция | Тип |
|---|---|---|---|
| SUCCESS | Запрос успешно обработан | Продолжить выполнение | |
| BAD_REQUEST | Ошибка в синтаксисе запроса, пропущены обязательные поля | Проверить запрос | N |
| INTERNAL_ERROR | Неизвестная внутренняя ошибка | Связаться с разработчиками | N |
| ABORTED | Операция не выполнена (например, по причине инвалидации локов, TRANSACTION_LOCKS_INVALIDATE в подробных сообщениях об ошибке) | Повторить всю транзакцию | R |
| UNAUTHENTICATED | Требуется аутентификация. | Проверить использующийся токен. С актуальным токеном повторить запрос. | N |
| UNAUTHORIZED | Отсутствует доступ к запрашиваемому объекту (таблица, директория) | Запросить доступ у администратора БД. | N |
| UNAVAILABLE | Часть системы недоступна | Повторить последнее действие (запрос) | R |
| UNDETERMINED | Состояние транзакции неизвестно. В результате выполнения запроса произошёл сбой, из-за которого невозможно определить состояние транзакции. На запросы, завершившиеся с таким статусом, распространяются гарантии целостности и атомарности транзакции. То есть либо все изменения зафиксированы, либо вся транзакция отменена. | Для идемпотентных транзакций можно повторить всю транзакцию с небольшой задержкой. В противном случае реакция зависит от логики приложения. | C |
| OVERLOADED | Часть системы перегружена | Повторить последнее действие (запрос), снизить интенсивность запросов | R |
| SCHEME_ERROR | Запрос не соответствует схеме | Исправить запрос или схему | N |
| GENERIC_ERROR | Неклассифицируемая ошибка, возможно, связанная с запросом | Посмотреть на подробное сообщение об ошибке, связаться с разработчиками | N |
| TIMEOUT | Запрос не выполнен за отведенное время | Можно повторить для идемпотентных запросов | C |
| BAD_SESSION | Данная сессия больше недоступна | Пересоздать сессию | R |
| PRECONDITION_FAILED | Запрос не может быть выполнен для данного состояния (например, вставка в таблицу с существующим ключом) | Исправить состояние или запрос и повторить | C |
| TRANSPORT_UNAVAILABLE | Транспортная ошибка, endpoint недоступен или разрыв соединения, с невозможностью его переустановить | Проверить endpoint или другие настройки сети | C |
| CLIENT_RESOURCE_EXHAUSTED | Недостаточно свободных ресурсов для обслуживания запроса | Снизить интенсивность запросов, проверить клиентскую балансировку | R |
| CLIENT_DEADLINE_EXCEEDED | Запрос не был обработан за заданный клиентский таймаут, иная сетевая проблема | Проверить корректность заданного таймаута, наличие сетевого доступа, проверить endpoint или другие настройки сети снизить интенсивность запросов, оптимизировать запросы | C |