DevOps Wissensdatenbank
DevOps Wissensdatenbank

Fehlgeschlagene Builds schnell mithilfe der Jenkins CLI beheben

Diagnostizieren und beheben Sie Jenkins-Build-Fehler schnell mit diesem umfassenden Leitfaden zur Jenkins CLI. Erfahren Sie, wie Sie detaillierte Konsolenprotokolle abrufen, Fehler mithilfe von \`grep\` filtern, Build-Umgebungsvariablen mithilfe leistungsstarker Groovy-Skripte überprüfen und Builds effizient erneut ausführen. Dieser Artikel stattet Sie mit den praktischen Befehlen und Best Practices aus, um Ausfallzeiten zu minimieren und die Fehlerbehebung Ihrer CI/CD-Prozesse schneller und effektiver als je zuvor zu gestalten.

42 Aufrufe

Schnelles Beheben fehlgeschlagener Builds mit der Jenkins CLI

Jenkins ist das Rückgrat von Continuous Integration- und Continuous Delivery (CI/CD)-Pipelines für unzählige Organisationen. Obwohl es die Build-, Test- und Bereitstellungsprozesse automatisiert, sind Build-Fehler ein unvermeidlicher Teil der Softwareentwicklung. Wenn ein Build fehlschlägt, sind eine schnelle Diagnose und Behebung entscheidend, um Ausfallzeiten zu minimieren und die Entwicklung voranzutreiben.

Während die Jenkins-Weboberfläche umfangreiche Informationen liefert, ist manchmal der schnellste Weg zur Fehlerbehebung direkt über die Jenkins Command Line Interface (CLI). Die CLI bietet eine leistungsstarke, skriptfähige und oft schnellere Alternative zur Navigation in der Benutzeroberfläche, insbesondere für sich wiederholende Aufgaben oder bei der Arbeit mit zahlreichen Build-Protokollen. Diese Anleitung führt Sie durch die Nutzung der Jenkins CLI, um Build-Fehler schnell zu diagnostizieren, detaillierte Protokolle abzurufen, Umgebungsvariablen zu inspizieren und Builds effizient neu zu starten.

Warum die Jenkins CLI zur Fehlerbehebung verwenden?

Die Jenkins CLI bietet mehrere Vorteile für die Fehlerbehebung:

  • Geschwindigkeit: Protokolle und Informationen schnell abrufen, ohne die Browsernavigation.
  • Automatisierung: Fehlerbehebungsschritte in Skripte oder automatisierte Berichte integrieren.
  • Fernzugriff: Diagnosen von jedem Terminal mit Netzwerkzugriff auf Ihre Jenkins-Instanz durchführen.
  • Effizienz: Protokolle und Informationen mit Standard-Shell-Tools wie grep, awk und sed filtern.

Voraussetzungen

Bevor Sie mit der Fehlerbehebung mit der Jenkins CLI beginnen können, stellen Sie Folgendes sicher:

  1. Jenkins-Server läuft: Eine aktive Jenkins-Instanz, auf die Sie administrativen Zugriff haben.
  2. Jenkins CLI JAR: Laden Sie die Datei jenkins-cli.jar von Ihrer Jenkins-Instanz herunter. Sie finden sie normalerweise unter JENKINS_URL/jnlpJars/jenkins-cli.jar.
  3. Authentifizierung: Die CLI erfordert eine Authentifizierung. Die empfohlene Methode ist die Verwendung eines API-Tokens für einen Jenkins-Benutzer. Generieren Sie ein API-Token über Ihr_Benutzername -> Configure -> Add new Token.

Einrichten der CLI

Laden Sie zuerst die jenkins-cli.jar herunter:

wget JENKINS_URL/jnlpJars/jenkins-cli.jar
# Oder mit curl
curl -O JENKINS_URL/jnlpJars/jenkins-cli.jar

Um die Befehle zu vereinfachen, können Sie Umgebungsvariablen für Ihre Jenkins-URL, Ihren Benutzernamen und Ihr API-Token festlegen:

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

# Alias für den CLI-Befehl zur Bequemlichkeit
alias jcli='java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN"'

Nun können Sie einfach jcli gefolgt vom Befehl verwenden.

Identifizieren fehlgeschlagener Builds

Der erste Schritt bei der Fehlerbehebung ist die Identifizierung, welcher Job und welcher Build fehlgeschlagen ist. Obwohl die CLI keinen direkten Befehl zum Auflisten nur fehlgeschlagener Builds hat, können Sie Jobs auflisten und sie dann inspizieren oder Groovy für erweiterte Filterung verwenden.

Auflisten von Jobs

Um eine Liste aller Jobs auf Ihrer Jenkins-Instanz anzuzeigen:

jcli list-jobs

Dies liefert eine grundlegende Liste. Um detailliertere Informationen zu einem bestimmten Job zu erhalten, einschließlich seines letzten Build-Status, verwenden Sie get-job:

jcli get-job MyPipelineJob

Die Ausgabe (standardmäßig im XML-Format) enthält Informationen wie lastFailedBuild, lastSuccessfulBuild usw., die Sie parsen können.

Tipp: Groovy für erweiterte Filterung verwenden

Für erweiterte Filterung, insbesondere zum Auffinden spezifischer fehlgeschlagener Builds, können Sie Groovy-Skripte über die CLI ausführen. Dies ist unglaublich leistungsfähig.

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

Abrufen detaillierter Build-Protokolle

Der häufigste und wichtigste Schritt bei der Fehlerbehebung ist die Überprüfung der Build-Protokolle (Konsolenausgabe). Die Jenkins CLI macht dies unkompliziert.

Konsolenausgabe abrufen

Um die vollständige Konsolenausgabe eines bestimmten Builds abzurufen, verwenden Sie den Befehl console:

jcli console MyPipelineJob 123

Ersetzen Sie MyPipelineJob durch den Namen Ihres Jobs und 123 durch die Build-Nummer. Dies gibt das gesamte Protokoll in Ihr Terminal aus.

Protokolle nach Fehlern filtern

Bei umfangreichen Protokollen ist die manuelle Analyse ineffizient. Verwenden Sie grep, um relevante Fehlermeldungen, Stack-Traces oder Schlüsselwörter schnell zu finden.

jcli console MyPipelineJob 123 | grep -iE "error|fail|exception|stacktrace"
  • -i: Ignoriert Groß-/Kleinschreibung.
  • -E: Verwendet erweiterte reguläre Ausdrücke (erlaubt | für ODER).

Dieser Befehl grenzt die Ausgabe erheblich ein und hilft Ihnen, die Fehlerursache schneller zu ermitteln.

Live-Builds überwachen

Für Builds, die noch laufen, aber festzustecken scheinen oder langsam fehlschlagen, können Sie ihre Konsolenausgabe in Echtzeit überwachen, ähnlich wie tail -f:

jcli console MyPipelineJob LAST_BUILD_NUMBER --follow

Dies streamt kontinuierlich neue Protokolleinträge, sobald sie erscheinen, bis der Build abgeschlossen ist oder Sie den Befehl beenden.

Überprüfen von Build-Umgebungsvariablen

Umgebungsvariablen spielen oft eine entscheidende Rolle bei der Build-Ausführung und beeinflussen Pfade, Geheimnisse und Konfigurationen. Falsche oder fehlende Umgebungsvariablen können zu Build-Fehlern führen. Obwohl es keinen direkten CLI-Befehl zum Auflisten aller Umgebungsvariablen eines vergangenen Builds gibt, können Sie diese mit einem über die CLI ausgeführten Groovy-Skript abrufen.

Stellen Sie zunächst sicher, dass Ihre Pipeline explizit relevante Umgebungsvariablen ausgibt oder dass Sie Zugriff auf einen dumpEnvVars-Schritt haben (wenn Sie das Plugin "Pipeline Utility Steps" verwenden). Wenn nicht, können Sie Groovy verwenden.

Verwenden von Groovy zum Zugreifen auf Umgebungsvariablen

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

Dieses Skript stellt eine Verbindung zur Jenkins-API her, ruft den angegebenen Job und Build ab und durchläuft dann alle Umgebungsvariablen, die während der Ausführung dieses Builds gesetzt wurden, und gibt sie aus.

  • Sicherheitshinweis: Seien Sie vorsichtig beim Ausgeben von Umgebungsvariablen, da diese sensible Informationen (API-Schlüssel, Passwörter usw.) enthalten können. Tun Sie dies nur in sicheren Umgebungen und stellen Sie ordnungsgemäße Zugriffskontrollen sicher.

Analysieren von bühnenspezifischen Fehlern in Pipelines

Bei Jenkins Pipelines ist es entscheidend zu wissen, welche Bühne fehlgeschlagen ist. Während die rohe console-Ausgabe [Pipeline] stage-Marker anzeigt, die zur Abgrenzung von Bühnen dienen, bietet die CLI selbst keine strukturierte Möglichkeit, den Bühnenstatus direkt abzufragen, wie es die Benutzeroberfläche (z. B. Blue Ocean) tut.

Auffinden von Bühnenfehlern in Protokollen

Bei der Überprüfung der console-Ausgabe suchen Sie nach dem letzten [Pipeline] stage-Eintrag vor der Fehlermeldung oder dem Stack-Trace. Dies zeigt normalerweise die Bühne an, auf der der Fehler aufgetreten ist.

jcli console MyPipelineJob 123 | less

Innerhalb von less können Sie nach [Pipeline] stage suchen und dann scrollen, um den Fehler zu finden.

Erneutes Ausführen oder Neustarten fehlgeschlagener Builds

Sobald Sie die Grundursache eines Fehlers identifiziert und eine Korrektur angewendet haben (z. B. neuen Code gepusht, eine Konfiguration aktualisiert), möchten Sie den Build erneut ausführen. Die CLI bietet hierfür eine einfache Möglichkeit.

Erneutes Ausführen eines gesamten Builds

Um einen neuen Build für einen Job auszulösen:

jcli build MyPipelineJob

Wenn Ihr Job Parameter akzeptiert, können Sie diese mit der Option -p übergeben:

jcli build MyPipelineJob -p BRANCH=feature/fix-bug -p BUILD_VERSION=1.0.1
  • --wait (-s): Warten Sie, bis der Build abgeschlossen ist.
  • --verbose (-v): Zeigen Sie den Fortschritt und die Build-Protokolle an.
jcli build MyPipelineJob -p BRANCH=master --wait --verbose

Neustart ab einer bestimmten Bühne (Erweitert)

Die Jenkins CLI hat keinen direkten Befehl restart-stage. Das Neustarten einer Pipeline ab einer bestimmten Bühne ist hauptsächlich eine Funktion der Jenkins-Benutzeroberfläche (oft durch das "Pipeline Steps"-Plugin aktiviert) oder erfordert spezifische Pipeline-Logik.

Sie können jedoch einen ähnlichen Effekt erzielen, indem Sie Ihre Pipeline so gestalten, dass sie Parameter akzeptiert, die das Überspringen anfänglicher Bühnen ermöglichen. Zum Beispiel:

// In Ihrem 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 ...
    }
}

Dann können Sie diesen parametrisierten Build über die CLI auslösen, um die "Setup"-Bühne zu überspringen:

jcli build MyPipelineJob -p SKIP_SETUP_STAGE=true

Dieser Ansatz erfordert Voraussicht bei der Gestaltung Ihres Jenkinsfile, bietet aber eine leistungsstarke Steuerung der Pipeline-Ausführung über die CLI.

Erweiterte Fehlerbehebung mit Groovy (via CLI)

Die Befehle groovy und groovy-script ermöglichen die Ausführung von beliebigem Groovy-Code auf dem Jenkins-Controller. Dies bietet unübertroffenen Zugriff auf die interne API von Jenkins für tiefe Inspektion und Manipulation.

Beispiel: Abrufen von Build-Details

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

Dieses Skript ruft umfassende Informationen zu einem bestimmten Build ab, was von unschätzbarem Wert sein kann, um zu verstehen, warum ein Build fehlgeschlagen ist, insbesondere wenn das Konsolenprotokoll weniger klar ist.

Lokale Groovy-Skripte ausführen

Für komplexere Groovy-Skripte schreiben Sie diese in eine .groovy-Datei und führen Sie sie über groovy-script aus:

# 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."
}

Führen Sie es dann aus:

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

Dies ermöglicht die Versionskontrolle Ihrer Fehlerbehebungswerkzeuge.

Tipps für eine effiziente Fehlerbehebung

  • Seien Sie spezifisch: Verfeinern Sie Ihre Muster bei der Verwendung von grep. Suchen Sie nach spezifischen Fehlercodes, eindeutigen Meldungen oder Zeitstempeln.
  • Kontext ist entscheidend: Berücksichtigen Sie immer die umgebenden Protokollzeilen. Fehler haben oft Vorläufer oder Folgeinformationen, die mehr Kontext liefern.
  • Pipeline-Struktur: Gestalten Sie Ihre Jenkinsfiles mit klaren Bühnennamen und detaillierter Protokollierung innerhalb kritischer Schritte. Dies erleichtert die Identifizierung von Problemen.
  • Verwenden Sie tee: Beim Ausführen von CLI-Befehlen können Sie die Ausgabe an tee weiterleiten, um sie sowohl anzuzeigen als auch für spätere Analysen in einer Datei zu speichern.
    bash jcli console MyPipelineJob 123 | tee build_123_log.txt | grep -i error
  • Jenkins Systemprotokolle: Denken Sie daran, dass Jenkins selbst Systemprotokolle hat (JENKINS_HOME/logs). Manchmal ist ein Build-Fehler auf ein Problem im Jenkins-System zurückzuführen und nicht auf den Pipeline-Code. Sie können auf diese über die Benutzeroberfläche (Manage Jenkins -> System Log) oder direkt im Dateisystem des Jenkins-Servers zugreifen.

Fazit

Die Jenkins CLI ist ein unverzichtbares Werkzeug für Administratoren und Entwickler gleichermaßen und bietet eine schnelle und leistungsstarke Möglichkeit, mit Ihrer Jenkins-Instanz zu interagieren. Indem Sie die Befehle zum Abrufen von Protokollen, Inspizieren von Umgebungsvariablen (via Groovy) und effizienten Auslösen von Builds beherrschen, können Sie die Zeit für die Diagnose und Behebung von Build-Fehlern erheblich verkürzen. Integrieren Sie diese CLI-Techniken in Ihren täglichen Arbeitsablauf, um hochperformante und zuverlässige CI/CD-Pipelines aufrechtzuerhalten.

Erkunden Sie weiterhin die umfangreiche Jenkins CLI-Befehlsliste (jcli help) und die Leistungsfähigkeit von Groovy-Skripten, um noch fortschrittlichere Automatisierungs- und Fehlerbehebungsfunktionen zu erschließen.