Центр знаний DevOps
Центр знаний DevOps

Быстрое устранение неполадок неудачных сборок с помощью Jenkins CLI

Быстро диагностируйте и устраняйте сбои сборок Jenkins с помощью этого подробного руководства по Jenkins CLI. Узнайте, как извлекать подробные журналы консоли, фильтровать ошибки с помощью `grep`, проверять переменные среды сборки с помощью мощных скриптов Groovy и эффективно перезапускать сборки. Эта статья вооружит вас практическими командами и лучшими практиками для минимизации простоев, делая устранение неполадок в вашем CI/CD быстрее и эффективнее, чем когда-либо прежде.

40 просмотров

Быстрое устранение сбоев сборки с помощью Jenkins CLI

Jenkins является основой конвейеров непрерывной интеграции и непрерывной поставки (CI/CD) для бесчисленных организаций. Несмотря на то, что он автоматизирует процессы сборки, тестирования и развертывания, сбои сборки являются неизбежной частью разработки программного обеспечения. Когда сборка завершается неудачно, быстрая диагностика и устранение неполадок имеют решающее значение для минимизации времени простоя и поддержания прогресса разработки.

Хотя веб-интерфейс Jenkins предоставляет обширную информацию, иногда самый быстрый способ устранения неполадок — это прямой доступ через интерфейс командной строки Jenkins (CLI). CLI предлагает мощную, поддающуюся скриптованию и часто более быструю альтернативу навигации по пользовательскому интерфейсу, особенно для повторяющихся задач или при работе с многочисленными журналами сборки. Это руководство проведет вас через использование Jenkins CLI для быстрой диагностики сбоев сборки, получения подробных журналов, проверки переменных среды и эффективного перезапуска сборок.

Зачем использовать Jenkins CLI для устранения неполадок?

Jenkins CLI предоставляет несколько преимуществ для устранения неполадок:

  • Скорость: Быстро получайте журналы и информацию без навигации по браузеру.
  • Автоматизация: Интегрируйте шаги по устранению неполадок в скрипты или автоматизированные отчеты.
  • Удаленный доступ: Выполняйте диагностику из любого терминала с сетевым доступом к вашему экземпляру Jenkins.
  • Эффективность: Фильтруйте журналы и информацию с помощью стандартных инструментов командной строки, таких как grep, awk и sed.

Предварительные требования

Прежде чем приступить к устранению неполадок с помощью Jenkins CLI, убедитесь, что у вас есть следующее:

  1. Запущенный сервер Jenkins: Активный экземпляр Jenkins, к которому у вас есть административный доступ.
  2. Jenkins CLI JAR: Загрузите файл jenkins-cli.jar из вашего экземпляра Jenkins. Обычно его можно найти по адресу JENKINS_URL/jnlpJars/jenkins-cli.jar.
  3. Аутентификация: CLI требует аутентификации. Рекомендуемый метод — использовать API-токен для пользователя Jenkins. Сгенерируйте API-токен через Your_User_Name -> Configure -> Add new Token.

Настройка CLI

Сначала загрузите jenkins-cli.jar:

wget JENKINS_URL/jnlpJars/jenkins-cli.jar
# Или с помощью curl
curl -O JENKINS_URL/jnlpJars/jenkins-cli.jar

Чтобы упростить команды, вы можете установить переменные среды для URL-адреса Jenkins, имени пользователя и API-токена:

export JENKINS_URL="http://your-jenkins-instance.com"
export JENKINS_USER="your_username"
export JENKINS_API_TOKEN="your_api_token"

# Для удобства создайте псевдоним команды CLI
alias jcli='java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN"'

Теперь вы можете просто использовать jcli, за которым следует команда.

Определение неудачных сборок

Первый шаг в устранении неполадок — определить, какая задача и сборка завершились неудачно. Хотя у CLI нет прямой команды для перечисления только неудачных сборок, вы можете перечислять задачи, а затем проверять их, или использовать Groovy для более продвинутой фильтрации.

Перечисление задач

Чтобы увидеть список всех задач в вашем экземпляре Jenkins:

jcli list-jobs

Это предоставляет базовый список. Чтобы получить более подробную информацию о конкретной задаче, включая статус последней сборки, используйте get-job:

jcli get-job MyPipelineJob

Вывод (по умолчанию в формате XML) будет содержать такую информацию, как lastFailedBuild, lastSuccessfulBuild и т. д., которую вы можете разобрать.

Совет: Использование Groovy для продвинутой фильтрации

Для более продвинутой фильтрации, особенно для поиска конкретных неудачных сборок, вы можете выполнять Groovy-скрипты через CLI. Это невероятно мощно.

jcli groovy =
    'Jenkins.instance.getAllItems(hudson.model.Job.class).each { job ->
        def lastBuild = job.getLastBuild()
        if (lastBuild != null && lastBuild.result == hudson.model.Result.FAILURE) {
            println "Failed Job: ${job.name}, Build: ${lastBuild.number}"
        }
    }'

Получение подробных журналов сборки

Наиболее распространенным и важным шагом в устранении неполадок является просмотр журналов сборки (вывод консоли). Jenkins CLI делает это простым.

Получение вывода консоли

Чтобы получить полный вывод консоли конкретной сборки, используйте команду console:

jcli console MyPipelineJob 123

Замените MyPipelineJob на имя вашей задачи и 123 на номер сборки. Это выведет весь журнал в ваш терминал.

Фильтрация журналов на наличие ошибок

Когда журналы обширны, ручная их обработка неэффективна. Используйте grep для быстрого поиска релевантных сообщений об ошибках, трассировок стека или ключевых слов.

jcli console MyPipelineJob 123 | grep -iE "error|fail|exception|stacktrace"
  • -i: Игнорировать регистр.
  • -E: Использовать расширенные регулярные выражения (разрешает | для ИЛИ).

Эта команда значительно сужает вывод, помогая быстрее определить причину сбоя.

Мониторинг активных сборок

Для сборок, которые все еще выполняются, но кажутся зависшими или медленно завершаются с ошибкой, вы можете отслеживать их вывод консоли в режиме реального времени, аналогично tail -f:

jcli console MyPipelineJob LAST_BUILD_NUMBER --follow

Это будет непрерывно передавать новые записи журнала по мере их появления, пока сборка не завершится или вы не остановите команду.

Проверка переменных среды сборки

Переменные среды часто играют критическую роль в выполнении сборки, влияя на пути, секреты и конфигурацию. Неправильные или отсутствующие переменные среды могут привести к сбоям сборки. Хотя прямой команды CLI для перечисления всех переменных среды предыдущей сборки нет, вы можете получить их с помощью Groovy-скрипта, выполненного через CLI.

Сначала убедитесь, что ваш конвейер явно выводит релевантные переменные среды или что у вас есть доступ к шагу dumpEnvVars (если используется плагин Pipeline Utility Steps). Если нет, вы можете использовать Groovy.

Использование Groovy для доступа к переменным среды

jcli groovy =
    'def job = Jenkins.instance.getItemByFullName("MyPipelineJob")
    def build = job.getBuildByNumber(123)
    if (build) {
        build.getEnvironment().each { key, value ->
            println "${key}=${value}"
        }
    } else {
        println "Build 123 not found for MyPipelineJob"
    }'

Этот скрипт подключается к API Jenkins, извлекает указанную задачу и сборку, а затем перебирает и выводит все переменные среды, которые были установлены во время выполнения этой сборки.

  • Предупреждение о безопасности: Будьте осторожны при выводе переменных среды, так как они могут содержать конфиденциальную информацию (API-ключи, пароли и т. д.). Делайте это только в безопасных средах и обеспечьте надлежащий контроль доступа.

Анализ сбоев на уровне этапов в конвейерах

Для конвейеров Jenkins крайне важно знать, какой этап завершился неудачно. Хотя необработанный вывод console будет содержать маркеры [Pipeline] stage, которые помогают разделять этапы, сам CLI не предоставляет структурированного способа запроса статуса этапа напрямую, как это делает пользовательский интерфейс (например, Blue Ocean).

Поиск сбоев этапов в журналах

При просмотре вывода console ищите последнюю запись [Pipeline] stage перед сообщением об ошибке или трассировкой стека. Это обычно указывает на этап, где произошел сбой.

jcli console MyPipelineJob 123 | less

Внутри less вы можете искать [Pipeline] stage, а затем прокручивать, чтобы найти ошибку.

Повторный запуск или перезапуск неудачных сборок

После того как вы определили первопричину сбоя и применили исправление (например, отправили новый код, обновили конфигурацию), вам потребуется повторно запустить сборку. CLI предоставляет простой способ сделать это.

Повторный запуск всей сборки

Чтобы запустить новую сборку для задачи:

jcli build MyPipelineJob

Если ваша задача принимает параметры, вы можете передать их с помощью флага -p:

jcli build MyPipelineJob -p BRANCH=feature/fix-bug -p BUILD_VERSION=1.0.1
  • --wait (-s): Дождаться завершения сборки.
  • --verbose (-v): Отображать прогресс и журналы сборки.
jcli build MyPipelineJob -p BRANCH=master --wait --verbose

Перезапуск с определенного этапа (расширенно)

В Jenkins CLI нет прямой команды restart-stage. Перезапуск конвейера с определенного этапа — это в основном функция пользовательского интерфейса Jenkins (часто активируемая плагином "Pipeline Steps") или требует специальной логики конвейера.

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

// В вашем Jenkinsfile

parameters {
    booleanParam(name: 'SKIP_SETUP_STAGE', defaultValue: false, description: 'Skip the initial setup stage')
}

pipeline {
    agent any
    stages {
        stage('Setup') {
            when {
                expression { !params.SKIP_SETUP_STAGE }
            }
            steps {
                echo 'Running setup...'
                // ... setup steps ...
            }
        }
        stage('Build') {
            steps {
                echo 'Building application...'
                // ... build steps ...
            }
        }
        // ... other stages ...
    }
}

Затем вы можете запустить эту параметризованную сборку через CLI, чтобы пропустить этап "Setup":

jcli build MyPipelineJob -p SKIP_SETUP_STAGE=true

Этот подход требует предусмотрительности в дизайне вашего Jenkinsfile, но предлагает мощный контроль над выполнением конвейера через CLI.

Расширенное устранение неполадок с помощью Groovy (через CLI)

Команды groovy и groovy-script позволяют выполнять произвольный код Groovy на контроллере Jenkins. Это обеспечивает беспрецедентный доступ к внутреннему API Jenkins для глубокого анализа и манипулирования.

Пример: Получение сведений о сборке

jcli groovy =
    'def job = Jenkins.instance.getItemByFullName("MyPipelineJob")
    def build = job.getBuildByNumber(123)

    if (build) {
        println "Build #${build.number} for ${job.name}"
        println "Status: ${build.result}"
        println "Duration: ${build.durationString}"
        println "Description: ${build.description ?: "N/A"}"
        println "Causes:"
        build.getCauses().each { cause ->
            println "  - ${cause.shortDescription}"
        }
    } else {
        println "Build 123 not found for MyPipelineJob"
    }'

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

Выполнение локальных Groovy-скриптов

Для более сложных Groovy-скриптов напишите их в файле .groovy и выполните с помощью groovy-script:

# my_troubleshooting_script.groovy

def jobName = System.getenv('JOB_NAME') ?: 'MyPipelineJob'
def buildNumber = System.getenv('BUILD_NUMBER') ? Integer.parseInt(System.getenv('BUILD_NUMBER')) : 123

def job = Jenkins.instance.getItemByFullName(jobName)
def build = job?.getBuildByNumber(buildNumber)

if (build) {
    println "Build details for ${job.name} #${build.number}"
    println "Status: ${build.result}"
    build.getAction(hudson.model.ParametersAction.class)?.getParameters()?.each { p ->
        println "Param: ${p.name} = ${p.value}"
    }
} else {
    println "Job ${jobName} or Build ${buildNumber} not found."
}

Затем запустите его:

JOB_NAME=MyPipelineJob BUILD_NUMBER=123 jcli groovy-script my_troubleshooting_script.groovy

Это позволяет версионировать ваши инструменты для устранения неполадок.

Советы по эффективному устранению неполадок

  • Будьте конкретны: При использовании grep уточняйте свои шаблоны. Ищите конкретные коды ошибок, уникальные сообщения или временные метки.
  • Контекст — это ключ: Всегда учитывайте окружающие строки журнала. Ошибки часто имеют предшествующие или последующие сообщения, которые дают больше контекста.
  • Структура конвейера: Разрабатывайте свои Jenkinsfiles с четкими именами этапов и подробным журналированием в критически важных шагах. Это облегчает определение проблем.
  • Используйте tee: При выполнении команд CLI вы можете передавать вывод в tee, чтобы одновременно отображать его и сохранять в файл для последующего анализа.
    bash jcli console MyPipelineJob 123 | tee build_123_log.txt | grep -i error
  • Системные журналы Jenkins: Помните, что сам Jenkins имеет системные журналы (JENKINS_HOME/logs). Иногда сбой сборки происходит из-за проблемы в системе Jenkins, а не из-за кода конвейера. Вы можете получить доступ к ним через пользовательский интерфейс (Manage Jenkins -> System Log) или непосредственно в файловой системе сервера Jenkins.

Заключение

Jenkins CLI — это незаменимый инструмент как для администраторов, так и для разработчиков, предлагающий быстрый и мощный способ взаимодействия с вашим экземпляром Jenkins. Освоив команды для получения журналов, проверки переменных среды (через Groovy) и эффективного запуска сборок, вы можете значительно сократить время, затрачиваемое на диагностику и устранение сбоев сборки. Интегрируйте эти методы CLI в свой повседневный рабочий процесс, чтобы поддерживать высокопроизводительные и надежные конвейеры CI/CD.

Продолжайте изучать обширный список команд Jenkins CLI (jcli help) и мощь Groovy-скриптов, чтобы раскрыть еще более продвинутые возможности автоматизации и устранения неполадок.