Centro di Conoscenza DevOps
Centro di Conoscenza DevOps

Risoluzione rapida dei problemi delle build non riuscite utilizzando la CLI di Jenkins

Diagnostica e risolvi rapidamente gli errori delle build di Jenkins con questa guida completa alla CLI di Jenkins. Impara come recuperare i log dettagliati della console, filtrare gli errori usando `grep`, ispezionare le variabili d'ambiente di build tramite potenti script Groovy e rieseguire le build in modo efficiente. Questo articolo ti fornisce i comandi pratici e le best practice per ridurre al minimo i tempi di inattività, rendendo la risoluzione dei problemi CI/CD più veloce ed efficace che mai.

49 visualizzazioni

Risoluzione rapida degli errori di build con la CLI di Jenkins

Jenkins è la spina dorsale delle pipeline di integrazione continua e consegna continua (CI/CD) per innumerevoli organizzazioni. Sebbene automatizzi i processi di build, test e deployment, gli errori di build sono una parte inevitabile dello sviluppo software. Quando una build fallisce, la diagnosi e la risoluzione rapide sono fondamentali per ridurre al minimo i tempi di inattività e mantenere il progresso dello sviluppo.

Sebbene l'interfaccia web di Jenkins fornisca informazioni estese, a volte il modo più rapido per risolvere i problemi è direttamente tramite l'interfaccia a riga di comando (CLI) di Jenkins. La CLI offre un'alternativa potente, scriptabile e spesso più veloce alla navigazione nell'interfaccia utente, specialmente per attività ripetitive o quando si gestiscono numerosi log di build. Questa guida ti accompagnerà nell'utilizzo della CLI di Jenkins per diagnosticare rapidamente gli errori di build, recuperare log dettagliati, ispezionare variabili d'ambiente e riavviare efficientemente le build.

Perché usare la CLI di Jenkins per la risoluzione dei problemi?

La CLI di Jenkins offre diversi vantaggi per la risoluzione dei problemi:

  • Velocità: Recupera rapidamente log e informazioni senza navigazione del browser.
  • Automazione: Integra i passaggi di risoluzione dei problemi in script o report automatizzati.
  • Accesso remoto: Esegui la diagnostica da qualsiasi terminale con accesso di rete alla tua istanza Jenkins.
  • Efficienza: Filtra log e informazioni utilizzando strumenti shell standard come grep, awk e sed.

Prerequisiti

Prima di poter iniziare la risoluzione dei problemi con la CLI di Jenkins, assicurati di avere quanto segue:

  1. Server Jenkins in esecuzione: un'istanza Jenkins attiva a cui hai accesso amministrativo.
  2. JAR CLI di Jenkins: scarica il file jenkins-cli.jar dalla tua istanza Jenkins. Di solito puoi trovarlo su JENKINS_URL/jnlpJars/jenkins-cli.jar.
  3. Autenticazione: la CLI richiede l'autenticazione. Il metodo consigliato è utilizzare un token API per un utente Jenkins. Genera un token API tramite Nome_Utente -> Configura -> Aggiungi nuovo Token.

Configurazione della CLI

Innanzitutto, scarica jenkins-cli.jar:

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

Per semplificare i comandi, puoi impostare variabili d'ambiente per il tuo URL Jenkins, nome utente e token API:

export JENKINS_URL="http://la-tua-istanza-jenkins.com"
export JENKINS_USER="il_tuo_nome_utente"
export JENKINS_API_TOKEN="il_tuo_token_api"

# Alias per il comando CLI per comodità
alias jcli='java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN"'

Ora, puoi semplicemente usare jcli seguito dal comando.

Identificazione delle build fallite

Il primo passo nella risoluzione dei problemi è identificare quale job e quale build sono falliti. Sebbene la CLI non disponga di un comando diretto per elencare solo le build fallite, puoi elencare i job e quindi ispezionarli, o usare Groovy per un filtraggio più avanzato.

Elenco dei job

Per vedere un elenco di tutti i job sulla tua istanza Jenkins:

jcli list-jobs

Questo fornisce un elenco di base. Per ottenere informazioni più dettagliate su un job specifico, incluso lo stato della sua ultima build, usa get-job:

jcli get-job MioJobPipeline

L'output (in formato XML per impostazione predefinita) conterrà informazioni come lastFailedBuild, lastSuccessfulBuild, ecc., che puoi analizzare.

Suggerimento: Utilizzare Groovy per un filtraggio avanzato

Per un filtraggio più avanzato, specialmente per trovare build fallite specifiche, puoi eseguire script Groovy tramite la CLI. Questo è incredibilmente potente.

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 "Job Fallito: ${job.name}, Build: ${lastBuild.number}"
        }
    }'

Recupero dei log di build dettagliati

Il passaggio più comune e cruciale nella risoluzione dei problemi è la revisione dei log di build (output della console). La CLI di Jenkins rende questo processo semplice.

Ottenere l'output della console

Per recuperare l'intero output della console di una build specifica, usa il comando console:

jcli console MioJobPipeline 123

Sostituisci MioJobPipeline con il nome del tuo job e 123 con il numero della build. Questo scaricherà l'intero log nel tuo terminale.

Filtrare i log per errori

Quando i log sono estesi, analizzarli manualmente è inefficiente. Sfrutta grep per trovare rapidamente messaggi di errore pertinenti, stack trace o parole chiave.

jcli console MioJobPipeline 123 | grep -iE "error|fail|exception|stacktrace"
  • -i: Ignora maiuscole/minuscole.
  • -E: Usa espressioni regolari estese (consente | per OR).

Questo comando restringe significativamente l'output, aiutandoti a individuare più velocemente la causa del fallimento.

Monitoraggio delle build in tempo reale

Per le build ancora in corso ma che sembrano bloccate o falliscono lentamente, puoi monitorare il loro output della console in tempo reale in modo simile a tail -f:

jcli console MioJobPipeline ULTIMO_NUMERO_BUILD --follow

Questo trasmetterà continuamente nuove voci di log man mano che appaiono, finché la build non sarà completata o non interromperai il comando.

Ispezione delle variabili d'ambiente di build

Le variabili d'ambiente svolgono spesso un ruolo critico nell'esecuzione della build, influenzando percorsi, segreti e configurazioni. Variabili d'ambiente errate o mancanti possono portare a errori di build. Sebbene non esista un comando CLI diretto per elencare tutte le variabili d'ambiente di una build passata, puoi recuperarle utilizzando uno script Groovy eseguito tramite la CLI.

Innanzitutto, assicurati che la tua pipeline stampi esplicitamente le variabili d'ambiente pertinenti o che tu abbia accesso a uno step dumpEnvVars (se utilizzi il plugin Pipeline Utility Steps). In caso contrario, puoi usare Groovy.

Utilizzo di Groovy per accedere alle variabili d'ambiente

jcli groovy =
    'def job = Jenkins.instance.getItemByFullName("MioJobPipeline")
    def build = job.getBuildByNumber(123)
    if (build) {
        build.getEnvironment().each { key, value ->
            println "${key}=${value}"
        }
    } else {
        println "Build 123 non trovata per MioJobPipeline"
    }'

Questo script si connette all'API di Jenkins, recupera il job e la build specificati, quindi itera e stampa tutte le variabili d'ambiente che sono state impostate durante l'esecuzione di quella build.

  • Avviso di sicurezza: presta attenzione quando stampi le variabili d'ambiente, poiché potrebbero contenere informazioni sensibili (chiavi API, password, ecc.). Fallo solo in ambienti sicuri e assicurati controlli di accesso appropriati.

Analisi dei fallimenti specifici di fase nelle pipeline

Per le pipeline Jenkins, sapere quale fase è fallita è fondamentale. Sebbene l'output grezzo di console mostri i marcatori [Pipeline] stage, che aiutano a delineare le fasi, la CLI stessa non fornisce un modo strutturato per interrogare direttamente lo stato della fase come fa l'interfaccia utente (ad es. Blue Ocean).

Individuazione dei fallimenti di fase nei log

Quando si esamina l'output di console, cercare l'ultima voce [Pipeline] stage prima del messaggio di errore o dello stack trace. Questo indica solitamente la fase in cui si è verificato il fallimento.

jcli console MioJobPipeline 123 | less

All'interno di less, puoi cercare [Pipeline] stage e quindi scorrere per trovare l'errore.

Riesecuzione o riavvio delle build fallite

Una volta identificata la causa principale di un fallimento e applicata una correzione (ad es. eseguito push di nuovo codice, aggiornata una configurazione), vorrai rieseguire la build. La CLI offre un modo semplice per farlo.

Riesecuzione di un'intera build

Per attivare una nuova build per un job:

jcli build MioJobPipeline

Se il tuo job accetta parametri, puoi passarli usando il flag -p:

jcli build MioJobPipeline -p BRANCH=feature/fix-bug -p BUILD_VERSION=1.0.1
  • --wait (-s): Attendi il completamento della build.
  • --verbose (-v): Visualizza progressi e log di build.
jcli build MioJobPipeline -p BRANCH=master --wait --verbose

Riavvio da una fase specifica (Avanzato)

La CLI di Jenkins non dispone di un comando diretto restart-stage. Riavviare una pipeline da una fase specifica è principalmente una funzionalità dell'interfaccia utente di Jenkins (spesso abilitata dal plugin "Pipeline Steps") o richiede una logica di pipeline specifica.

Tuttavia, puoi ottenere un effetto simile progettando la tua pipeline per accettare parametri che consentono di saltare le fasi iniziali. Ad esempio:

// Nel tuo Jenkinsfile

parameters {
    booleanParam(name: 'SKIP_SETUP_STAGE', defaultValue: false, description: 'Salta la fase di setup iniziale')
}

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

Quindi, puoi attivare questa build parametrizzata tramite CLI per saltare la fase "Setup":

jcli build MioJobPipeline -p SKIP_SETUP_STAGE=true

Questo approccio richiede lungimiranza nella progettazione del tuo Jenkinsfile, ma offre un potente controllo sull'esecuzione della pipeline tramite la CLI.

Risoluzione avanzata dei problemi con Groovy (tramite CLI)

I comandi groovy e groovy-script ti consentono di eseguire codice Groovy arbitrario sul controller Jenkins. Ciò fornisce un accesso senza precedenti all'API interna di Jenkins per ispezioni e manipolazioni approfondite.

Esempio: Ottenere dettagli di build

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

    if (build) {
        println "Build #${build.number} per ${job.name}"
        println "Stato: ${build.result}"
        println "Durata: ${build.durationString}"
        println "Descrizione: ${build.description ?: "N/A"}"
        println "Cause:"
        build.getCauses().each { cause ->
            println "  - ${cause.shortDescription}"
        }
    } else {
        println "Build 123 non trovata per MioJobPipeline"
    }'

Questo script recupera informazioni complete su una build specifica, che possono essere inestimabili per capire perché una build è fallita, specialmente se il log della console è meno chiaro.

Esecuzione di script Groovy locali

Per script Groovy più complessi, scrivili in un file .groovy ed eseguilo tramite groovy-script:

# mio_script_risoluzione_problemi.groovy

def jobName = System.getenv('JOB_NAME') ?: 'MioJobPipeline'
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 "Dettagli build per ${job.name} #${build.number}"
    println "Stato: ${build.result}"
    build.getAction(hudson.model.ParametersAction.class)?.getParameters()?.each { p ->
        println "Parametro: ${p.name} = ${p.value}"
    }
} else {
    println "Job ${jobName} o Build ${buildNumber} non trovati."
}

Quindi eseguilo:

JOB_NAME=MioJobPipeline BUILD_NUMBER=123 jcli groovy-script mio_script_risoluzione_problemi.groovy

Questo consente il controllo delle versioni dei tuoi strumenti di risoluzione dei problemi.

Suggerimenti per una risoluzione efficiente dei problemi

  • Sii specifico: quando usi grep, affina i tuoi pattern. Cerca codici di errore specifici, messaggi unici o timestamp.
  • Il contesto è fondamentale: considera sempre le righe di log circostanti. Gli errori hanno spesso precursori o messaggi di follow-up che forniscono più contesto.
  • Struttura della pipeline: progetta i tuoi Jenkinsfile con nomi di fase chiari e logging dettagliato all'interno dei passaggi critici. Ciò rende più facile individuare i problemi.
  • Usa tee: quando esegui comandi CLI, puoi inviare l'output a tee per visualizzarlo e salvarlo in un file per analisi future.
    bash jcli console MioJobPipeline 123 | tee build_123_log.txt | grep -i error
  • Log di sistema Jenkins: ricorda che Jenkins stesso ha log di sistema (JENKINS_HOME/logs). A volte un errore di build è dovuto a un problema di sistema di Jenkins, non al codice della pipeline. Puoi accedervi tramite l'interfaccia utente (Gestisci Jenkins -> Log di sistema) o direttamente sul filesystem del server Jenkins.

Conclusione

La CLI di Jenkins è uno strumento indispensabile sia per gli amministratori che per gli sviluppatori, offrendo un modo rapido e potente per interagire con la tua istanza Jenkins. Padroneggiando i comandi per recuperare log, ispezionare variabili d'ambiente (tramite Groovy) e attivare efficientemente build, puoi ridurre significativamente il tempo impiegato per diagnosticare e risolvere errori di build. Integra queste tecniche CLI nel tuo flusso di lavoro quotidiano per mantenere pipeline CI/CD altamente performanti e affidabili.

Continua a esplorare l'elenco completo dei comandi CLI di Jenkins (jcli help) e la potenza dello scripting Groovy per sbloccare capacità di automazione e risoluzione dei problemi ancora più avanzate.