Centro de Conocimiento DevOps
Centro de Conocimiento DevOps

Solución Rápida de Fallos en Compilaciones Usando la CLI de Jenkins

Diagnostica y resuelve rápidamente los fallos en las compilaciones de Jenkins con esta guía completa de la CLI de Jenkins. Aprende a recuperar registros detallados de la consola, filtrar errores usando `grep`, inspeccionar variables del entorno de compilación a través de potentes scripts de Groovy y volver a ejecutar compilaciones de manera eficiente. Este artículo te equipa con los comandos prácticos y las mejores prácticas para minimizar el tiempo de inactividad, haciendo que la solución de problemas de tu CI/CD sea más rápida y efectiva que nunca.

43 vistas

Solución rápida de problemas de compilaciones fallidas mediante la CLI de Jenkins

Jenkins es la columna vertebral de las canalizaciones de integración continua y entrega continua (CI/CD) para innumerables organizaciones. Si bien automatiza los procesos de compilación, prueba e implementación, las fallas de compilación son una parte inevitable del desarrollo de software. Cuando una compilación falla, el diagnóstico y la resolución rápidos son fundamentales para minimizar el tiempo de inactividad y mantener el desarrollo avanzando.

Si bien la interfaz de usuario web (UI) de Jenkins proporciona información extensa, a veces la forma más rápida de solucionar problemas es directamente a través de la Interfaz de Línea de Comandos (CLI) de Jenkins. La CLI ofrece una alternativa potente, programable y, a menudo, más rápida que navegar por la interfaz de usuario, especialmente para tareas repetitivas o cuando se manejan numerosos registros de compilación. Esta guía lo guiará a través del aprovechamiento de la CLI de Jenkins para diagnosticar rápidamente fallas de compilación, recuperar registros detallados, inspeccionar variables de entorno y reiniciar compilaciones de manera eficiente.

¿Por qué utilizar la CLI de Jenkins para la solución de problemas?

La CLI de Jenkins ofrece varias ventajas para la solución de problemas:

  • Velocidad: Obtenga registros e información rápidamente sin necesidad de navegar por el navegador.
  • Automatización: Integre los pasos de solución de problemas en scripts o informes automatizados.
  • Acceso remoto: Realice diagnósticos desde cualquier terminal con acceso de red a su instancia de Jenkins.
  • Eficiencia: Filtre registros e información utilizando herramientas de shell estándar como grep, awk y sed.

Requisitos previos

Antes de que pueda comenzar a solucionar problemas con la CLI de Jenkins, asegúrese de tener lo siguiente:

  1. Servidor Jenkins en ejecución: Una instancia de Jenkins activa a la que tenga acceso administrativo.
  2. JAR de la CLI de Jenkins: Descargue el archivo jenkins-cli.jar de su instancia de Jenkins. Por lo general, puede encontrarlo en JENKINS_URL/jnlpJars/jenkins-cli.jar.
  3. Autenticación: La CLI requiere autenticación. El método recomendado es utilizar un token API para un usuario de Jenkins. Genere un token API a través de Your_User_Name -> Configure -> Add new Token.

Configuración de la CLI

Primero, descargue el jenkins-cli.jar:

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

Para simplificar los comandos, puede establecer variables de entorno para su URL de Jenkins, nombre de usuario y token API:

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

# Cree un alias para el comando CLI para mayor comodidad
alias jcli='java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN"'

Ahora, puede usar simplemente jcli seguido del comando.

Identificación de compilaciones fallidas

El primer paso en la solución de problemas es identificar qué trabajo y compilación han fallado. Si bien la CLI no tiene un comando directo para enumerar solo las compilaciones fallidas, puede enumerar los trabajos y luego inspeccionarlos, o usar Groovy para un filtrado más avanzado.

Listar trabajos

Para ver una lista de todos los trabajos en su instancia de Jenkins:

jcli list-jobs

Esto proporciona una lista básica. Para obtener información más detallada sobre un trabajo específico, incluido el estado de su última compilación, use get-job:

jcli get-job MyPipelineJob

La salida (en formato XML por defecto) contendrá información como lastFailedBuild, lastSuccessfulBuild, etc., que puede analizar.

Consejo: Uso de Groovy para filtrado avanzado

Para un filtrado más avanzado, especialmente para encontrar compilaciones fallidas específicas, puede ejecutar scripts Groovy a través de la CLI. Esto es increíblemente 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 "Failed Job: ${job.name}, Build: ${lastBuild.number}"
        }
    }'

Recuperación de registros detallados de compilación

El paso más común y crucial en la solución de problemas es revisar los registros de compilación (salida de la consola). La CLI de Jenkins simplifica esto.

Obtener la salida de la consola

Para recuperar la salida completa de la consola de una compilación específica, use el comando console:

jcli console MyPipelineJob 123

Reemplace MyPipelineJob con el nombre de su trabajo y 123 con el número de compilación. Esto volcará todo el registro en su terminal.

Filtrado de registros en busca de errores

Cuando los registros son extensos, analizarlos manualmente es ineficiente. Aproveche grep para encontrar rápidamente mensajes de error relevantes, seguimientos de pila o palabras clave.

jcli console MyPipelineJob 123 | grep -iE "error|fail|exception|stacktrace"
  • -i: Ignorar mayúsculas y minúsculas.
  • -E: Usar expresiones regulares extendidas (permite | para OR).

Este comando reduce significativamente la salida, ayudándole a identificar la causa de la falla más rápido.

Monitoreo de compilaciones en vivo

Para las compilaciones que todavía se están ejecutando, pero parecen estar atascadas o fallando lentamente, puede monitorear la salida de su consola en tiempo real de forma similar a tail -f:

jcli console MyPipelineJob LAST_BUILD_NUMBER --follow

Esto transmitirá continuamente nuevas entradas de registro a medida que aparezcan, hasta que finalice la compilación o usted detenga el comando.

Inspección de variables de entorno de compilación

Las variables de entorno a menudo juegan un papel fundamental en la ejecución de la compilación, influyendo en las rutas, secretos y la configuración. Las variables de entorno incorrectas o faltantes pueden provocar fallas en la compilación. Si bien no existe un comando CLI directo para enumerar todas las variables de entorno de una compilación anterior, puede recuperarlas utilizando un script Groovy ejecutado a través de la CLI.

Primero, asegúrese de que su canalización imprima explícitamente las variables de entorno relevantes o que tenga acceso a un paso dumpEnvVars (si usa el complemento Pipeline Utility Steps). Si no, puede usar Groovy.

Uso de Groovy para acceder a variables de entorno

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 a la API de Jenkins, recupera el trabajo y la compilación especificados, y luego itera e imprime todas las variables de entorno que se configuraron durante la ejecución de esa compilación.

  • Advertencia de seguridad: Tenga cuidado al imprimir variables de entorno, ya que pueden contener información confidencial (claves API, contraseñas, etc.). Solo haga esto en entornos seguros y garantice los controles de acceso adecuados.

Análisis de fallas específicas de etapas en canalizaciones

Para las canalizaciones de Jenkins, saber qué etapa falló es crucial. Si bien la salida console sin procesar mostrará marcadores [Pipeline] stage, que ayudan a delinear las etapas, la CLI en sí misma no proporciona una forma estructurada de consultar el estado de la etapa directamente como lo hace la UI (por ejemplo, Blue Ocean).

Localización de fallas de etapa en registros

Al revisar la salida de la console, busque la última entrada [Pipeline] stage antes del mensaje de error o el seguimiento de pila. Esto generalmente indica la etapa donde ocurrió la falla.

jcli console MyPipelineJob 123 | less

Dentro de less, puede buscar [Pipeline] stage y luego desplazarse para encontrar el error.

Volver a ejecutar o reiniciar compilaciones fallidas

Una vez que haya identificado la causa raíz de una falla y haya aplicado una solución (por ejemplo, haya enviado código nuevo, haya actualizado una configuración), querrá volver a ejecutar la compilación. La CLI ofrece una forma sencilla de hacerlo.

Volver a ejecutar una compilación completa

Para activar una nueva compilación para un trabajo:

jcli build MyPipelineJob

Si su trabajo acepta parámetros, puede pasarlos usando el indicador -p:

jcli build MyPipelineJob -p BRANCH=feature/fix-bug -p BUILD_VERSION=1.0.1
  • --wait (-s): Esperar a que la compilación se complete.
  • --verbose (-v): Mostrar progreso y registros de compilación.
jcli build MyPipelineJob -p BRANCH=master --wait --verbose

Reinicio desde una etapa específica (Avanzado)

La CLI de Jenkins no tiene un comando directo restart-stage. Reiniciar una canalización desde una etapa específica es principalmente una característica de la UI de Jenkins (a menudo habilitada por el complemento "Pipeline Steps") o requiere lógica de canalización específica.

Sin embargo, puede lograr un efecto similar diseñando su canalización para que acepte parámetros que permitan omitir las etapas iniciales. Por ejemplo:

// En su 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 ...
    }
}

Luego, puede activar esta compilación parametrizada a través de la CLI para omitir la etapa "Setup":

jcli build MyPipelineJob -p SKIP_SETUP_STAGE=true

Este enfoque requiere previsión en el diseño de su Jenkinsfile pero ofrece un potente control sobre la ejecución de la canalización a través de la CLI.

Solución avanzada de problemas con Groovy (a través de la CLI)

Los comandos groovy y groovy-script le permiten ejecutar código Groovy arbitrario en el controlador de Jenkins. Esto proporciona un acceso incomparable a la API interna de Jenkins para una inspección y manipulación profundas.

Ejemplo: Obtención de detalles de compilación

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 información completa sobre una compilación específica, lo que puede ser invaluable para comprender por qué falló una compilación, especialmente si el registro de la consola es menos claro.

Ejecución de scripts Groovy locales

Para scripts Groovy más complejos, escríbalos en un archivo .groovy y ejecútelos a través de 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."
}

Luego ejecútelo:

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

Esto permite controlar la versión de sus herramientas de solución de problemas.

Consejos para una solución de problemas eficiente

  • Sea específico: Cuando use grep, refine sus patrones. Busque códigos de error específicos, mensajes únicos o marcas de tiempo.
  • El Contexto es Clave: Considere siempre las líneas de registro circundantes. Los errores a menudo tienen precursores o mensajes de seguimiento que proporcionan más contexto.
  • Estructura de la canalización: Diseñe sus Jenkinsfiles con nombres de etapas claros y registro detallado dentro de los pasos críticos. Esto facilita la identificación de problemas.
  • Use tee: Al ejecutar comandos CLI, puede canalizar la salida a tee para mostrarla y guardarla en un archivo para su análisis posterior.
    bash jcli console MyPipelineJob 123 | tee build_123_log.txt | grep -i error
  • Registros del Sistema Jenkins: Recuerde que Jenkins mismo tiene registros del sistema (JENKINS_HOME/logs). A veces, una falla de compilación se debe a un problema del sistema Jenkins, no al código de la canalización. Puede acceder a ellos a través de la UI (Manage Jenkins -> System Log) o directamente en el sistema de archivos del servidor Jenkins.

Conclusión

La CLI de Jenkins es una herramienta indispensable tanto para administradores como para desarrolladores, ya que ofrece una forma rápida y potente de interactuar con su instancia de Jenkins. Al dominar los comandos para recuperar registros, inspeccionar variables de entorno (a través de Groovy) y activar compilaciones de manera eficiente, puede reducir significativamente el tiempo dedicado a diagnosticar y resolver fallas de compilación. Integre estas técnicas de CLI en su flujo de trabajo diario para mantener canalizaciones CI/CD de alto rendimiento y confiables.

Continúe explorando la extensa lista de comandos de la CLI de Jenkins (jcli help) y el poder de los scripts Groovy para desbloquear capacidades de automatización y solución de problemas aún más avanzadas.