← Volver al listado de tecnologías ← Índice de GitLab Runners

Monitoreo, Troubleshooting y Buenas Practicas

25 de febrero de 2025 Por: Artiko

gitlabrunnersmonitoreoprometheusbuenas-practicas

Monitoreo, Troubleshooting y Buenas Practicas

Monitoreo con Prometheus

GitLab Runner expone metricas en el puerto 9252.

Activar metricas

# config.toml
listen_address = ":9252"

Metricas disponibles

Metrica	Descripcion
`gitlab_runner_jobs`	Jobs activos por runner y estado
`gitlab_runner_jobs_total`	Total de jobs procesados
`gitlab_runner_api_request_statuses_total`	Requests a la API de GitLab
`gitlab_runner_errors_total`	Errores por tipo
`process_resident_memory_bytes`	Uso de memoria del proceso

Dashboard basico de Grafana

Importar dashboard ID 1860 de Grafana Labs o crear uno con:

Jobs activos vs concurrentes (capacidad)
Duracion promedio de jobs
Tasa de errores API
Memoria y CPU del runner

Troubleshooting

Debug mode

sudo gitlab-runner --debug run

Logs del runner

# Systemd
sudo journalctl -u gitlab-runner -f

# Docker
docker logs -f gitlab-runner

Problemas comunes

Job pendiente mucho tiempo

Causa: No hay runner disponible con los tags correctos
Solucion:
  1. Verificar tags del job vs tags del runner
  2. Verificar que el runner esta online: Settings > CI/CD > Runners
  3. Verificar concurrent y limit

Error “docker: command not found”

Causa: Shell executor sin Docker instalado
Solucion:
  - Instalar Docker en la maquina del runner
  - O cambiar a Docker executor

Error “Permission denied”

Causa: El usuario gitlab-runner no tiene permisos
Solucion:
  sudo usermod -aG docker gitlab-runner
  sudo service gitlab-runner restart

Job lento en Docker executor

Causa: pull_policy = "always" descarga imagenes cada vez
Solucion:
  [runners.docker]
    pull_policy = ["if-not-present"]

Cache no funciona entre jobs

Causa: Jobs en runners diferentes, cache local
Solucion:
  - Usar cache S3 compartido
  - O usar artifacts en lugar de cache

Buenas practicas

1. Un runner, un proposito

No mezcles runners de build con runners de deploy. Usa tags para separar:

build:
  tags: [build, docker]

deploy:
  tags: [deploy, production]

2. Usa imagenes especificas

# Mal
image: node:latest

# Bien
image: node:20.11-alpine3.19

latest cambia sin aviso y rompe pipelines.

3. Fail fast

Pon los jobs rapidos primero:

stages:
  - lint      # Segundos
  - test      # Minutos
  - build     # Minutos
  - deploy    # Variable

4. Paraleliza con needs

lint:
  stage: quality
  needs: []  # Empieza inmediatamente

unit_test:
  stage: quality
  needs: []

integration_test:
  stage: quality
  needs: [unit_test]

5. Limita el output

[[runners]]
  output_limit = 4096  # 4MB max de log

Jobs que imprimen mucho consumen memoria y storage.

6. Limpia regularmente

# Limpiar imagenes Docker no usadas
docker system prune -af --filter "until=168h"

# Limpiar builds viejos
gitlab-runner verify --delete

7. Actualiza el runner

GitLab recomienda mantener el runner en la misma version major que tu instancia GitLab.

# Verificar version
gitlab-runner --version

# Actualizar
sudo apt-get update && sudo apt-get install gitlab-runner

Checklist de produccion

← Volver al indice