Centro de Conhecimento DevOps
Centro de Conhecimento DevOps

Solucionando Problemas de Builds com Falha Rapidamente Usando a CLI do Jenkins

Diagnostique e resolva rapidamente falhas de build do Jenkins com este guia abrangente sobre a CLI do Jenkins. Aprenda a recuperar logs de console detalhados, filtrar erros usando o `grep`, inspecionar variáveis de ambiente de build através de poderosos scripts Groovy e reexecutar builds com eficiência. Este artigo o equipa com comandos práticos e melhores práticas para minimizar o tempo de inatividade, tornando a sua solução de problemas de CI/CD mais rápida e eficaz do que nunca.

44 visualizações

Resolução Rápida de Falhas de Compilação Usando o Jenkins CLI

Jenkins é a espinha dorsal de pipelines de integração contínua e entrega contínua (CI/CD) para inúmeras organizações. Embora automatize os processos de compilação, teste e implantação, falhas de compilação são uma parte inevitável do desenvolvimento de software. Quando uma compilação falha, o diagnóstico e a resolução rápidos são cruciais para minimizar o tempo de inatividade e manter o desenvolvimento em andamento.

Embora a interface de usuário web (UI) do Jenkins forneça informações extensas, às vezes a maneira mais rápida de solucionar problemas é diretamente através da Interface de Linha de Comando (CLI) do Jenkins. A CLI oferece uma alternativa poderosa, programável e frequentemente mais rápida para navegar pela UI, especialmente para tarefas repetitivas ou ao lidar com vários logs de compilação. Este guia irá guiá-lo no uso do Jenkins CLI para diagnosticar rapidamente falhas de compilação, recuperar logs detalhados, inspecionar variáveis de ambiente e reiniciar compilações de forma eficiente.

Por que Usar o Jenkins CLI para Solução de Problemas?

O Jenkins CLI oferece várias vantagens para a solução de problemas:

  • Velocidade: Busque logs e informações rapidamente sem navegação no navegador.
  • Automação: Integre etapas de solução de problemas em scripts ou relatórios automatizados.
  • Acesso Remoto: Realize diagnósticos de qualquer terminal com acesso à rede à sua instância Jenkins.
  • Eficiência: Filtre logs e informações usando ferramentas de shell padrão como grep, awk e sed.

Pré-requisitos

Antes de começar a solucionar problemas com o Jenkins CLI, certifique-se de ter o seguinte:

  1. Servidor Jenkins em Execução: Uma instância Jenkins ativa à qual você tem acesso administrativo.
  2. JAR do Jenkins CLI: Baixe o arquivo jenkins-cli.jar da sua instância Jenkins. Geralmente, você pode encontrá-lo em JENKINS_URL/jnlpJars/jenkins-cli.jar.
  3. Autenticação: A CLI requer autenticação. O método recomendado é usar um token de API para um usuário Jenkins. Gere um token de API via Seu_Nome_de_Usuário -> Configurar -> Adicionar novo Token.

Configurando a CLI

Primeiro, baixe o jenkins-cli.jar:

wget JENKINS_URL/jnlpJars/jenkins-cli.jar
# Ou usando curl
curl -O JENKINS_URL/jnlpJars/jenkins-cli.jar

Para simplificar comandos, você pode definir variáveis de ambiente para sua URL Jenkins, nome de usuário e token de API:

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

# Alias do comando CLI para conveniência
alias jcli='java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN"'

Agora, você pode simplesmente usar jcli seguido do comando.

Identificando Compilações Falhas

O primeiro passo na solução de problemas é identificar qual job e compilação falharam. Embora a CLI não tenha um comando direto para listar apenas compilações falhas, você pode listar jobs e depois inspecioná-los, ou usar Groovy para filtragem mais avançada.

Listando Jobs

Para ver uma lista de todos os jobs na sua instância Jenkins:

jcli list-jobs

Isso fornece uma lista básica. Para obter informações mais detalhadas sobre um job específico, incluindo o status de sua última compilação, use get-job:

jcli get-job MyPipelineJob

A saída (no formato XML por padrão) conterá informações como lastFailedBuild, lastSuccessfulBuild, etc., que você pode analisar.

Dica: Usando Groovy para Filtragem Avançada

Para filtragem mais avançada, especialmente para encontrar compilações falhas específicas, você pode executar scripts Groovy via CLI. Isso é incrivelmente poderoso.

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}"
        }
    }'

Recuperando Logs Detalhados de Compilação

O passo mais comum e crucial na solução de problemas é revisar os logs de compilação (saída do console). O Jenkins CLI torna isso simples.

Obtendo a Saída do Console

Para recuperar a saída completa do console de uma compilação específica, use o comando console:

jcli console MyPipelineJob 123

Substitua MyPipelineJob pelo nome do seu job e 123 pelo número da compilação. Isso despejará o log inteiro no seu terminal.

Filtrando Logs para Erros

Quando os logs são extensos, analisá-los manualmente é ineficiente. Aproveite o grep para encontrar rapidamente mensagens de erro relevantes, rastreamentos de pilha ou palavras-chave.

jcli console MyPipelineJob 123 | grep -iE "error|fail|exception|stacktrace"
  • -i: Ignorar maiúsculas/minúsculas.
  • -E: Usar expressões regulares estendidas (permite | para OU).

Este comando reduz significativamente a saída, ajudando você a identificar a causa da falha mais rapidamente.

Monitorando Compilações ao Vivo

Para compilações que ainda estão em execução, mas parecem travadas ou estão falhando lentamente, você pode monitorar a saída do console em tempo real, similar a tail -f:

jcli console MyPipelineJob LAST_BUILD_NUMBER --follow

Isso transmitirá continuamente novas entradas de log à medida que aparecem, até que a compilação termine ou você interrompa o comando.

Inspecionando Variáveis de Ambiente da Compilação

Variáveis de ambiente frequentemente desempenham um papel crítico na execução da compilação, influenciando caminhos, segredos e configurações. Variáveis de ambiente incorretas ou ausentes podem levar a falhas de compilação. Embora não haja um comando CLI direto para listar todas as variáveis de ambiente de uma compilação passada, você pode recuperá-las usando um script Groovy executado via CLI.

Primeiro, certifique-se de que seu pipeline imprima explicitamente as variáveis de ambiente relevantes ou que você tenha acesso a uma etapa dumpEnvVars (se estiver usando o plugin Pipeline Utility Steps). Caso contrário, você pode usar Groovy.

Usando Groovy para Acessar Variáveis de Ambiente

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"
    }'

Este script se conecta à API Jenkins, recupera o job e a compilação especificados e, em seguida, itera e imprime todas as variáveis de ambiente que foram definidas durante a execução dessa compilação.

  • Aviso de Segurança: Tenha cuidado ao imprimir variáveis de ambiente, pois elas podem conter informações sensíveis (chaves de API, senhas, etc.). Faça isso apenas em ambientes seguros e garanta controles de acesso adequados.

Analisando Falhas Específicas de Estágio em Pipelines

Para Jenkins Pipelines, saber qual estágio falhou é crucial. Embora a saída console bruta mostre marcadores [Pipeline] stage, que ajudam a delinear estágios, a própria CLI não oferece uma maneira estruturada de consultar o status do estágio diretamente como a UI (por exemplo, Blue Ocean) faz.

Localizando Falhas de Estágio em Logs

Ao revisar a saída do console, procure pela última entrada [Pipeline] stage antes da mensagem de erro ou rastreamento de pilha. Isso geralmente indica o estágio onde a falha ocorreu.

jcli console MyPipelineJob 123 | less

Dentro do less, você pode pesquisar por [Pipeline] stage e então rolar para encontrar o erro.

Reexecutando ou Reiniciando Compilações Falhas

Depois de identificar a causa raiz de uma falha e aplicar uma correção (por exemplo, enviou novo código, atualizou uma configuração), você desejará reexecutar a compilação. A CLI oferece uma maneira direta de fazer isso.

Reexecutando uma Compilação Inteira

Para acionar uma nova compilação para um job:

jcli build MyPipelineJob

Se o seu job aceitar parâmetros, você pode passá-los usando a flag -p:

jcli build MyPipelineJob -p BRANCH=feature/fix-bug -p BUILD_VERSION=1.0.1
  • --wait (-s): Aguarda a conclusão da compilação.
  • --verbose (-v): Exibe o progresso e os logs de compilação.
jcli build MyPipelineJob -p BRANCH=master --wait --verbose

Reiniciando de um Estágio Específico (Avançado)

O Jenkins CLI não possui um comando restart-stage direto. Reiniciar um pipeline de um estágio específico é principalmente um recurso da UI do Jenkins (frequentemente ativado pelo plugin "Pipeline Steps") ou requer lógica de pipeline específica.

No entanto, você pode obter um efeito similar projetando seu pipeline para aceitar parâmetros que permitam pular estágios iniciais. Por exemplo:

// No seu 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 ...
            }
        }
        // ... outros estágios ...
    }
}

Então, você pode acionar esta compilação parametrizada via CLI para pular o estágio "Setup":

jcli build MyPipelineJob -p SKIP_SETUP_STAGE=true

Esta abordagem requer planejamento prévio no design do seu Jenkinsfile, mas oferece controle poderoso sobre a execução do pipeline via CLI.

Solução de Problemas Avançada com Groovy (via CLI)

Os comandos groovy e groovy-script permitem executar código Groovy arbitrário no controlador Jenkins. Isso fornece acesso inigualável à API interna do Jenkins para inspeção e manipulação profundas.

Exemplo: Obtendo Detalhes da Compilação

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"
    }'

Este script recupera informações abrangentes sobre uma compilação específica, o que pode ser inestimável para entender por que uma compilação falhou, especialmente se o log do console for menos claro.

Executando Scripts Groovy Locais

Para scripts Groovy mais complexos, escreva-os em um arquivo .groovy e execute-o via 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."
}

Então execute-o:

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

Isso permite o controle de versão de suas ferramentas de solução de problemas.

Dicas para Solução de Problemas Eficiente

  • Seja Específico: Ao usar grep, refine seus padrões. Procure por códigos de erro específicos, mensagens únicas ou timestamps.
  • O Contexto é Fundamental: Sempre considere as linhas de log circundantes. Erros frequentemente têm precursores ou mensagens de acompanhamento que fornecem mais contexto.
  • Estrutura do Pipeline: Projete seus Jenkinsfiles com nomes de estágio claros e logging verboso dentro das etapas críticas. Isso facilita a identificação de problemas.
  • Use tee: Ao executar comandos CLI, você pode direcionar a saída para tee para exibi-la e salvá-la em um arquivo para análise posterior.
    bash jcli console MyPipelineJob 123 | tee build_123_log.txt | grep -i error
  • Logs do Sistema Jenkins: Lembre-se de que o próprio Jenkins possui logs de sistema (JENKINS_HOME/logs). Às vezes, uma falha de compilação é devido a um problema do sistema Jenkins, e não ao código do pipeline. Você pode acessá-los via UI (Gerenciar Jenkins -> Log do Sistema) ou diretamente no sistema de arquivos do servidor Jenkins.

Conclusão

O Jenkins CLI é uma ferramenta indispensável para administradores e desenvolvedores, oferecendo uma maneira rápida e poderosa de interagir com sua instância Jenkins. Ao dominar os comandos para recuperar logs, inspecionar variáveis de ambiente (via Groovy) e acionar compilações de forma eficiente, você pode reduzir significativamente o tempo gasto no diagnóstico e resolução de falhas de compilação. Integre essas técnicas de CLI em seu fluxo de trabalho diário para manter pipelines CI/CD de alto desempenho e confiáveis.

Continue explorando a extensa lista de comandos do Jenkins CLI (jcli help) e o poder do script Groovy para desbloquear capacidades ainda mais avançadas de automação e solução de problemas.