Типовые сценарии диагностики и устранения проблем с использованием Grafana Loki и Explorer

Пример поиска и анализа ошибки при деплойменте/активации потока

Этот сценарий применяется, когда поток не переходит в статус Active (остаётся в Activating/Failed) сразу после попытки активации. Чаще всего причина - ошибка инициализации контекста Camel из‑за отсутствия или некорректности зависимостей: бинов, соединений (например, SFTP), секретов и т. п.

Поиск ошибки

1. Зайдите в Grafana, в левом боковом меню выберите Explorer.
2. Из выпадающего списка источников данных выберите Loki.
3. В блоке Label filters задайте источник данных service , оператор = и значение configuration-server - именно этот сервис инициирует активацию и валидирует конфигурацию. Если есть подозрение на проблемы синхронизации состояния, измените значение на state-collector.
4. В поле Line contains введите текст ERROR (или более узкие фразы: failed to activate, initialization failed, bean not found, connection not resolved).
5. Добавьте формат парсинга Logfmt:
   1. Нажмите + Operations.
   2. В разделе Formats выберите Logfmt.
   3. Отметьте значение "Strict".
6. Добавьте фильтр по идентификатору потока:
   1. + Operations → Label filters → Label filter expression. Задайте:
   • Label - route_id
   • Operator- =.
   • Value - идентификатор потока из интерфейса ESB. (Например, 54443a4c-9386-4267-a3e5-efb874yuf510)
7. Выберите временной диапазон, совпадающий с попыткой активации (обычно достаточно «Last 30m»).
8. Нажмите Run query.

Анализ результатов запроса

В панели результатов Grafana Explorer вы увидите строки логов, разбитые на поля за счёт Logfmt. Обратите внимание на следующие поля:

• error_type: тип ошибки (например, initialization, configuration, secret, state_sync)
• message: точное описание ошибки (например, «Bean with name 'sftpConnector' not found»)
• route_id: подтверждение, что ошибка относится к нужному потоку.
• upstream_component (если есть): компонент или зависимость, которая вызвала сбой.

Типовые ошибки и действия администратора

Ниже приведены типовые ошибки инициализации и активации потока, которые можно встретить в структурированных логах configuration-server. Для каждой ошибки указан фрагмент лога (Logfmt), интерпретация и конкретные действия администратора в интерфейсе Bercut ESB.

Фрагмент лога (Logfmt)	Пояснение	Действие
error_type="initialization" message="Bean with name 'sftpConnector' not found"	Не зарегистрирован нужный бин	Проверить регистрацию бина в контейнере, наличие и версию модуля/артефакта
error_type="configuration" message="Connection reference 'sftp-conn-01' not found"	В конфигурации потока указан несуществующий connection_id	Проверить наличие соединения в Connection Manager, корректность ID, отсутствие опечаток
error_type="secret" message="Secret 'sftp-creds' not found or expired"	Секрет отсутствует, истёк или у потока нет прав на его чтение	Проверить существование секрета, срок действия, права доступа потока к хранилищу секретов
error_type="validation" message="SFTP configuration is invalid: missing host/port"	Конфигурация соединения неполная	Убедиться, что заполнены все обязательные поля (host, port, user, authentication)
error_type="state_sync" message="Failed to apply configuration for flow"	State Collector не смог применить конфигурацию	Проверить доступность Configuration Server, таймауты, состояние инстансов State Collector

Действия по устранению и проверка результата

Действия:

• Исправьте конфигурацию: добавьте/обновите соединение, секрет, бин, заполните обязательные поля.
• Проверьте права доступа и актуальность версий артефактов.
• Повторите активацию потока.
• При подозрении на рассинхронизацию - перезапустите State Collector (в соответствии с регламентом эксплуатации).
• Если проблема повторяется - откатите поток на предыдущую стабильную версию.

Проверка результата:

• Статус потока в UI - Active.
• В Loki - нет новых ошибок инициализации/активации для этого потока.
• В метриках:
  • Рост configuration_server_route_activation_count{status="success"} (или аналогичной метрики активации в вашей версии).
  • Отсутствие всплесков в configuration_server_route_activation_errors_total.

Пример поиска и анализа ошибки при обработке данных (Runtime‑ошибки)

Этот сценарий применяется, когда поток успешно активирован (статус Active), но падает при обработке входящих сообщений. Чаще всего причина - ошибки логики трансформации или доступа к данным: некорректный SQL‑запрос, ошибочный XSLT/JSONata, неверный маппинг полей, таймаут внешнего вызова и т. п.

Поиск ошибки

1. Откройте интерфейс Explorer в Grafana.
2. Из выпадающего списка источников данных выберите Loki.
3. В блоке Label filters задайте:
   • Label: service
   • Operator: =
   • Value: Core. Если подозреваете проблемы балансировки или проксирования перед обработкой, дополнительно можно проверить API Gateway.
4. В поле Line contains введите ERROR, а также при необходимости более узкие фразы: SQL syntax, XSLT error, transformation failed, timeout, connection refused.
5. Добавьте формат парсинга Logfmt:
   1. Нажмите + Operations.
   2. В разделе Formats выберите Logfmt.
   3. Отметьте значение Strict.
      Это критично: именно в структурированном виде вы увидите block_name, correlation_id, message.
6. Добавьте фильтр по идентификатору потока:
   1. + Operations → Label filters → Label filter expression.
   2. Задайте:
      • Label: route_id
      • Operator: =
      • Value: идентификатор потока из интерфейса ESB (например, 54443a4c-9386-4267-a3e5-efb874yuf510).
7. (Опционально) Добавьте фильтр по correlation_id, если у вас есть ID упавшего запроса (из UI O&M или из ответа клиенту):
   • Label: correlation_id
   • Operator: =
   • Value: configuration-server. Если есть подозрение на проблемы синхронизации состояния (например, статус не обновляется или «залипает»), дополнительно проверьте логи сервиса state-collector.
8. Выберите временной диапазон, совпадающий с моментом падения (обычно достаточно «Last 1h» или «Last 4h» при редком трафике).
9. Нажмите Run query.

Результатом поиска будут записи с уровнем логирования ERROR.

Анализ результатов запроса

После выполнения запроса в панели результатов вы увидите структурированные логи (за счёт Logfmt Strict). Обращайте внимание на следующие поля:

• error_type: тип ошибки (sql, xslt, transformation, external_call, validation). Позволяет сразу понять класс проблемы.
• block_name (или node_id): имя блока в Flow Editor, где произошла ошибка. Это прямой якорь для исправления логики.
• message: точное описание ошибки (например, текст ошибки от СУБД или XSLT‑процессора).
• correlation_id: уникальный ID запроса, по которому можно отследить полный путь сообщения и входные данные.
• upstream_component (если присутствует): компонент или внешняя система, которая вернула ошибку.

Типовые ошибки и действия администратора

Ниже приведены типовые runtime‑ошибки, которые можно встретить в структурированных логах ESB Core. Для каждой ошибки указан фрагмент лога (Logfmt), интерпретация и конкретные действия администратора в интерфейсе Bercut ESB.

Фрагмент лога (Logfmt)	Пояснение	Действие
error_type="sql" message="SQL syntax error near 'SELECT'"	В блоке с SQL‑запросом синтаксическая ошибка	Открыть блок в Flow Editor, проверить SQL‑синтаксис, экранирование кавычек, корректность алиасов
error_type="sql" message="relation \"orders\" does not exist"	Таблица/представление не найдено в целевой БД	Проверить подключение к БД, наличие таблицы, схему, права доступа пользователя соединения
error_type="xslt" message="XPath evaluation failed: Undefined variable '$input'"	Ошибка в XSLT: используется неопределённая переменная или неверный XPath	Открыть XSLT в редакторе блока, проверить переменные, пространства имён, соответствие входной XML‑схеме
error_type="transformation" message="JSONata error: invalid token"	Ошибка выражения JSONata (в JSON‑трансформации)	Проверить JSONata‑выражение, экранирование спецсимволов, валидность входных данных
error_type="external_call" message="Connection refused to host=db.prod port=5432"	Недоступность внешней системы (БД, сервис)	Проверить сетевой доступ, статус инстанса БД/сервиса, корректность connection_id и секретов
error_type="timeout" message="Request to http://external-api timed out after 30s"	Превышено время ожидания ответа от внешней системы	Проверить таймауты в соединении, нагрузку на внешний сервис, наличие блокировок/очередей
error_type="validation" message="Schema validation failed: missing required field 'orderId'"	Входные данные не соответствуют ожидаемой схеме	Проверить формат входящего сообщения, правила валидации в потоке, примеры запросов от клиента

Действия по устранению и проверка результата

Действия:

• Исправьте логику в проблемном блоке: SQL‑запрос, XSLT/JSONata‑выражения, правила маппинга.
• Проверьте конфигурацию соединения и секреты (хост, порт, учётные данные, права).
• При проблемах с доступностью - устраните сетевые ограничения или восстановите внешний сервис.
• При таймаутах - скорректируйте таймауты или оптимизируйте запрос/логику.
• Если проблема в данных - обновите правила валидации или добавьте обработку ошибок (fallback‑ветки, dead letter queue).
• Повторите отправку тестового сообщения (через UI или тестовый клиент).

Проверка результата:

• Статус потока в UI остаётся Active (он не должен падать при исправлении логики).
• В Loki - нет новых ошибок с тем же block_name и похожими message.
• В метриках:
  • Рост core_route_invoke_count_total{route_id="<ID>"} - поток обрабатывает запросы.
  • Снижение core_route_error_count_total{route_id="<ID>", error_type="<тип>"}.
  • Нормальная длительность обработки (гистограммы core_route_duration_seconds).
• В UI O&M: успешные сообщения в истории, отсутствие повторных ошибок по тем же correlation_id.