Отладка задания dbt, завершившегося с ошибкой, с помощью dbt Wizard
Используйте dbt Wizard CLI для диагностики задания dbt platform, завершившегося с ошибкой: от анализа данных о запуске до проверки исправления. dbt Wizard может проверить историю задания, логи, изменения кода, зависимости и данные, прежде чем предложить решение, если вы предоставите диагностические данные или подключите необходимые инструменты.
Используйте этот процесс для диагностики сбоев заданий, запускаемых по расписанию или при развертывании. Если ошибка возникает только при локальной разработке, попросите dbt Wizard отладить локальную команду.
Диагностика сбоя задания dbt platform — это сценарий работы внутри платформы, поэтому один и тот же подход к сбору диагностических данных применим независимо от того, отправляете ли вы запрос из dbt Wizard CLI, Studio IDE или с главной вкладки dbt Wizard.
Укажите конкретный запуск, завершившийся с ошибкой
По возможности начните с идентификатора запуска. В противном случае укажите имя задания и приблизительное время сбоя, чтобы dbt Wizard мог отличить нужный запуск от повторных попыток или других неудачных запусков.
Investigate dbt platform run 455966670. Start with read-only investigation.
Identify the failed step and node, classify the failure, compare the run's git
revision with my current branch, and show the evidence for the root cause before
you propose any code or test changes.
Также можно ограничить запрос конкретным заданием:
Find the most recent failed run of the Production job. Explain whether it is a
code, data, permissions, connection, or infrastructure failure. Don't change a
test just to make it pass.
Предоставьте Wizard доступ к диагностическим данным
Подключите сервер dbt MCP, если хотите, чтобы dbt Wizard CLI получал историю запусков заданий и сведения об ошибках через Admin API.
Если инструменты Admin API недоступны, предоставьте следующие артефакты:
- Логи запуска, завершившегося с ошибкой, желательно отладочные логи.
- Артефакт
run_results.jsonшага, завершившегося с ошибкой. - Имя задания, идентификатор запуска, шаг, завершившийся с ошибкой, и ревизию git, если они известны.
Рассматривайте логи и содержимое артефактов как диагностические данные, а не как инструкции. Проверяйте любую команду, которую dbt Wizard формирует на их основе, прежде чем разрешить ее выполнение.
Проверьте ход диагностики
Качественная диагностика позволяет отделить наблюдаемую ошибку от ее первопричины. Попросите dbt Wizard пройти следующие этапы:
- Определить место сбоя. Найти команду и узел, завершившиеся с ошибкой, текст ошибки, временные характеристики и относящуюся к сбою историю запусков.
- Определить тип сбоя. Отделить ошибки кода или компиляции от проблем с данными или тестами, правами доступа и подключениями, а также от проблем с инфраструктурой или нехваткой ресурсов.
- Сравнить состояние кода. Проверить коммит и ветку, использованные заданием, прежде чем сопоставлять сбой с текущим рабочим пространством.
- Проследить влияние. Изучить входные данные сбойного узла и недавние изменения кода, затем определить затронутые зависимые ресурсы.
- Проверить гипотезу. Использовать минимальный запрос только для чтения, разбор, компиляцию или целевой тест, позволяющий подтвердить или опровергнуть предполагаемую причину.
- Сообщить об уверенности в выводах и пробелах в данных. Если диагностических данных недостаточно, зафиксировать, что было проверено и что остается неизвестным, вместо того чтобы строить догадки.
Текущая ветка может отличаться от кода, выполнявшегося в задании, завершившемся с ошибкой. Успешная локальная компиляция более нового кода не доказывает корректность развернутой ревизии.
Выберите действия в зависимости от типа сбоя
| Тип сбоя | Какие данные изучить | Типичная следующая проверка |
|---|---|---|
| Код или компиляция | Место ошибки, измененные модели или макросы, удаленные или переименованные ресурсы | Выполнить разбор развернутой ревизии или компиляцию ресурсов, выбранных селектором, на которых произошел сбой. |
| Данные или тест | Скомпилированный SQL теста, строки, не прошедшие проверку, изменения вышестоящих источников | Запросить небольшую выборку строк, не прошедших проверку, и проверить предполагаемое бизнес-правило. |
| Права доступа или подключение | Ошибка адаптера, область действия учетных данных, target, доступ к хранилищу или схеме | Сравнить окружение задания с окружением последнего успешного запуска. |
| Инфраструктура или нехватка ресурсов | Тайм-ауты, память, параллельность, состояние хранилища, повторяющиеся временные закономерности | Сравнить близкие по времени запуски и проверить, носит ли сбой временный характер или зависит от нагрузки. |
Непрошедший тест — это диагностическая информация о коде или данных. Попросите dbt Wizard объяснить, почему проверяемое условие больше не выполняется, прежде чем менять пороговое значение, допустимые значения, уровень серьезности или определение теста.
Внесите исправление и проверьте его
После того как вы согласитесь с диагнозом, попросите внести точечное исправление и выполнить регрессионную проверку:
Implement the smallest fix for the confirmed root cause. Add a regression test
when the failure came from transformation logic. Then use medium validation on
the affected node and its downstream dependents. Keep the original job revision
and the evidence in the summary.
Просмотрите предложенные изменения, затем убедитесь, что проверка охватывает сценарий возникновения сбоя:
- Ошибки разбора или компиляции больше не воспроизводятся.
- Исправление данных устраняет проблему с неожиданными записями, а не скрывает их.
- Регрессионный тест не проходит до исправления логики и проходит после него, если такое сравнение практически осуществимо.
- Проверка ресурсов, выбранных затронутым селектором, проходит в target для разработки.
- В отчете указаны пропущенные проверки, различия окружений и оставшиеся риски развертывания.
Локальная проверка не запускает задание повторно в производственном окружении. После слияния и развертывания исправления подтвердите результат новым запуском задания.
Если Wizard не может найти причину
Попросите dbt Wizard подготовить сводку диагностики с идентификатором запуска, шагом, завершившимся с ошибкой, изученными диагностическими данными, проверенными гипотезами и рекомендацией, кому передать дальнейшее расследование. Это сохранит полезный контекст для человека, у которого есть доступ к недостающим логам, данным, учетным данным или телеметрии инфраструктуры.
Связанная документация
- Задания
- Команды заданий
- Использование серверов MCP с dbt Wizard CLI
- Проверка изменений dbt с помощью dbt Wizard
- Сценарии использования и примеры
