Привет, Хабр! Меня зовут Оксана, я системный аналитик в Сравни. Сегодня хочу рассказать о том, как мы разбирались с ошибками в интеграциях по API с нашими партнерами, какие инструменты для анализа ошибок нам тут помогали. Надеюсь, статья будет полезна для системных аналитиков и всех, кто работает с внешними API, особенно если интеграций много.

Внешние интеграции: что может пойти не так

Сравни – это финансовый маркетплейс. Мы помогаем людям получить финансовые и страховые услуги. Одна из ключевых бизнес-ценностей для пользователей – возможность сравнивать и оформлять вклады, кредиты, ипотеку, ОСАГО, каско, страховку путешественников и дальше по списку.

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

Сложность тут в том, что каждый партнёр в ответах на наши запросы к их API может присылать десятки разных типов ошибок. Все эти ошибки нужно смотреть и анализировать – это довольно много материала для анализа. 

Ещё одна сложность состоит в том, что у каждого партнёра используется свой формат представления ошибок. Пример: партнёр не смог обработать наш запрос, произошла непредвиденная ситуация. Ответы на запросы по таким “непредвиденным ситуациям” мы складываем в группу “критические ошибки”.  Вот примеры таких ошибок от трёх разных партнёров:

Формулировки не самые единообразные, правда? 

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

Техническая сложность: мы анализировали ошибки от партнёров в Kibana, а там (как бы это помягче сказать) не всегда максимально удобно проводить анализ, когда нужно найти причину ошибки. Выглядело это примерно вот так:

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

Как мы оптимизировали работу с ошибками

Итак, что же мы со всем этим сделали? 

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

• валидация данных

• законодательные ограничения

• критические ошибки

• маппинг данных

• сервер не держит нагрузку

• системные ошибки

• другие ошибки

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

Выглядело это следующим образом: мы завели увесистую таблицу в Google Spreadsheets, где по каждому партнёру разбирали каждую ошибку. Мы записывали эту ошибку в таблицу, присваивали ей группу и подгруппу, а также подробно описывали, что эта ошибка означает и с чем она связана – сделали маппинг ошибок. 

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

Там у нас есть поле «Источник ошибки»: мы можем заводить не только ошибки, которые нам присылает партнёр, но и наши внутренние ошибки. 

Пару слов о том, как это устроено под капотом. Бэкенд парсит ошибку от партнёра, мы эту ошибку сохраняем в так называемую котировку (пул запросов). Далее ошибка по правилу сопоставления попадает в подгруппу. 

Группа ошибки по ID соединяется с подгруппой; подгруппа соединяется с правилом; правило соединяется с таблицей, где каждой ошибке присвоен ID котировки и, соответственно, по этому ID идёт соединение с таблицами заказов и расчётов. 

Выбор инструмента для анализа ошибок

Итак, мы перемаппили кучу ошибок. Сейчас у нас заведено 800 правил сопоставления для всех партнёров. 

Когда мы выбирали инструмент для анализа ошибок, в шортлисте у нас было два варианта: Power BI и Snowflake. Второй не подошёл нам по скорости: на наших объёмах информации дашборды грузились пару часов. Соответственно, выбор пал на Power BI.

В Power BI мы завели два основных отчёта. Первый – это отчёт сгруппированных ошибок. Здесь мы можем выбрать конфигурацию: источник запросов (сайт, мобильное приложение и так далее), определенного партнёра и дату. Можем посмотреть ошибки по разным группам: что у нас происходит, где ошибки выросли, а где уменьшились.

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

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

Второй основной отчёт – «Отчёт новых ошибок». Сюда попадает всё то, что не попало в предыдущий отчет, то есть это те ошибки, на которые ещё не заведены правила сопоставления. Выглядит это так:

В этом отчёте мы можем увидеть и проанализировать новые ошибки, экстренно отреагировать и сообщить о новых ошибках партнёрам. Или может возникнуть другая ситуация: мы что-то зарелизили, что повлияло на интеграцию, увидели появление новых ошибок – имеем возможность оперативно внести правки в интеграцию. 

Отчёты об ошибках есть, что дальше?

Раз в три месяца мы выгружаем статистику по ошибками и отдаём партнёрам. Это даёт им +1 источник для аналитики, они могут сравнить с собственной информацией о проблемах – что пошло не так, почему и где просели. 

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

Также отчёты помогают нам находить ошибки непосредственно в интеграциях. Я перепроверила: за время использования этого инструментария для двух десятков партнёров мы завели порядка 60 задач на исправления проблем интеграций.

Грабли и заборы

Немного расскажу об особенностях и ограничениях нашей системы. 

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

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

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

Работа над маппингом ошибок силами системных аналитиков заняла полгода. Здесь был человеческий фактор с обеих сторон: анализируем ошибки, задаём вопрос партнёру, они анализируют со своей стороны, возвращаются к нам с ответами, которые мы могли ждать очень долго.

Ещё одна особенность – необходимость учитывать изменения в ошибках. Со временем появляются новые ошибки и уходят старые. Если с новыми ошибками всё несколько проще – мы видим, что они появились и добавляем их в систему, то со старыми сложнее, потому что мы не узнаем о том, что они ушли, пока не сделаем руками специальную выгрузку. 

Маппинг и анализ ошибок от внешних API: рецепт

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

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

Один из ключевых факторов, почему мы решились изменить подход к анализу ошибок от внешних API – это не было для нас первым подобным решением. В ИТ-команде Сравни у нас есть принцип: вместо того, чтобы решать отдельно взятые проблемы, можно попробовать сделать инструмент, который будет помогать системно решать целый класс таких проблем. 

Так что если пойдёте прикидывать, что можно оптимизировать для работы с ошибками от внешних API на вашей стороне, в качестве шага 0 перепроверьте, а как у вас вообще принято поступать в инженерной команде – удобное для вас решение может прийти как раз оттуда.