dbr-logs

Получение и отображение логов Databricks-заданий из Unity Catalog Volumes.

Объединяет логи драйвера и исполнителей в хронологическом порядке с метками источника — можно передавать в grep, jq или отправлять в LLM.

Зачем это нужно

Отладка упавшего Databricks-задания требует навигации по глубоко вложенной, непоследовательно структурированной директории логов:

Ручной процесс поиска причины сбоя:

1. Найти запуск — идентификаторы запусков — непрозрачные строки вида 0311-170011-t5450avl, не читаемые человеком
2. Навигация по дереву — логи драйвера, исполнителей или оба? У какого из 9 исполнителей возникла ошибка?
3. Смешанное сжатие — ротированные файлы драйвера — plain text, ротированные файлы исполнителей — .gz. Нужно выполнить databricks fs cp + gunzip для чтения
4. Конкатенация ротированных файлов — один поток разбит на активный файл и несколько ротированных, которые нужно читать в хронологическом порядке
5. Повторение для каждого исполнителя — для задания с 9 исполнителями это потенциально 9 × 4 файла для проверки
6. Сопоставление временных меток — первопричина часто в одном источнике, а симптомы проявляются в другом

О том, как работает Python-логирование в Databricks и почему оно приводит к такой структуре, читайте в статье Everything You Wanted to Know About Python Logging in Databricks.

Существуют более тяжёлые альтернативы — Practitioner's Ultimate Guide to Scalable Logging от Databricks описывает полный пайплайн логирования, а также можно направлять логи Databricks в Datadog или аналогичные платформы наблюдаемости. Но эти решения несут значительные постоянные затраты и инфраструктурные накладные расходы для задачи, которая большинству команд нужна лишь изредка при отладке упавшего задания. dbr-logs — бесплатная альтернатива без инфраструктуры: установите CLI-инструмент, выполните одну команду, получите ответ.

dbr-logs заменяет ручной процесс одной командой. Инструмент обнаруживает структуру логов, скачивает и распаковывает все файлы, объединяет всё хронологически с метками источника и позволяет фильтровать по уровню, источнику или регулярному выражению.

Требования

• Python 3.11+ (протестировано на 3.11, 3.12, 3.13, 3.14)
• Databricks CLI с настроенным хотя бы одним профилем в ~/.databrickscfg (руководство по настройке)
• Unity Catalog Volumes в качестве назначения логов, настроенного для ваших Databricks-заданий (cluster_log_conf, указывающий на путь в Volumes)

Установка

# Установка как CLI-инструмент через uv (рекомендуется)
uv tool install dbr-logs

# Или через pipx (изолированное окружение)
pipx install dbr-logs

# Или через pip (используйте --user для глобальной установки без влияния на venv)
pip install --user dbr-logs

# Или запуск без установки
uvx dbr-logs <job-name>

Использование

# Получить логи последнего запуска задания
dbr-logs my-job-name

# Получить логи конкретного запуска
dbr-logs my-job-name --run-id 12345

# Использовать URL рабочего пространства Databricks
dbr-logs "https://dbc-xxx.cloud.databricks.com/jobs/12345/runs/67890?o=123"

# Показать только ошибки
dbr-logs my-job-name --level ERROR

# Сосредоточиться на логах приложения (подавить шум Spark/JVM)
dbr-logs my-job-name --focus

# Показать только логи исполнителей
dbr-logs my-job-name --source executor

# Показать последние 50 строк конкретного исполнителя
dbr-logs my-job-name --source executor:3 --tail 50

# Вывод в формате JSONL для передачи в jq
dbr-logs my-job-name --format jsonl | jq '.level'

# Логи за последний час
dbr-logs my-job-name --since 1h

Интеграция с Claude Code

dbr-logs включает плагин для Claude Code, позволяющий получать и анализировать логи прямо из диалога с Claude.

Установка плагина

# Вариант 1: плагин Claude Code
/marketplace add https://github.com/zencity/databricks-logs-reader
/plugin add dbr-logs

# Вариант 2: skills.sh (работает с Claude Code, Cursor, Windsurf и др.)
npx skills add zencity/databricks-logs-reader

CLI-инструмент всё равно нужно устанавливать отдельно (pip install dbr-logs или uv tool install dbr-logs), однако скилл также может использовать uvx как запасной вариант без установки.

Пример взаимодействия

Параметры