Depuración de flaky tests en CI/CD: APM y logs en GitHub

La depuración de flaky tests es uno de los retos más frustrantes para equipos de backend y SRE que operan pipelines de CI/CD. Cuando una prueba falla de forma intermitente, el tiempo medio de reparación (MTTR) se dispara y los acuerdos de nivel de servicio (SLA) se ponen en riesgo. En este artículo caminaremos paso a paso desde la concepción del proyecto hasta su lanzamiento, mostrando cómo correlacionar los logs de prueba con métricas de APM en GitHub Actions y GitLab. Al final, podrás replicar la arquitectura en tu propio entorno y reducir significativamente la incertidumbre de los flaky tests.

---

1. Planificación del proyecto

1.1 Definición de objetivos

• Reducir el MTTR de flaky tests en al menos un 30 %.
• Obtener visibilidad de latencia y errores a nivel de prueba mediante métricas APM.
• Mantener el tiempo total del pipeline dentro del 5 % del baseline.

1.2 Selección del stack tecnológico

Componente	Opción recomendada
CI/CD	GitHub Actions, GitLab CI
APM	Lescopr APM (instrumentación automática)
Logging	Structured JSON logs (stdout)
Dashboard	Lescopr SLA & Observability Dashboard

1.3 Arquitectura de alto nivel

La arquitectura se basa en instrumentación distribuida: cada job del pipeline envía trazas a Lescopr, mientras que los logs de prueba se etiquetan con el mismo trace_id. La correlación ocurre en tiempo real en el dashboard.

2. Implementación de instrumentación APM

2.1 Preparar el entorno de desarrollo

Instala el agente Lescopr en los contenedores de pruebas:

docker run -d \
  -e LESCOPR_TOKEN=$LESCPR_TOKEN \
  -e LESCOPR_SERVICE_NAME=my-service \
  lescopr/agent:latest

2.2 Añadir trazas a los tests

En un proyecto Python con pytest, agrega un fixture que cree una traza por test:

import lescopr
import uuid

@pytest.fixture(autouse=True)
def trace_test(request):
    trace_id = str(uuid.uuid4())
    lescopr.start_trace(trace_id, name=request.node.name)
    yield
    lescopr.end_trace(trace_id)

Para Node.js con Jest, la lógica es análoga usando el SDK de Lescopr.

2.3 Enriquecer los logs con trace_id

Modifica la configuración del logger para incluir el identificador de traza:

{
  "format": "json",
  "fields": {
    "trace_id": "${LESCPR_TRACE_ID}",
    "level": "${LEVEL}",
    "message": "${MESSAGE}"
  }
}

Con esta configuración, cada línea de log lleva la referencia que será usada para la correlación.

3. Integración con CI/CD y correlación de logs

3.1 Configurar GitHub Actions

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set Lescopr env
        run: echo "LESCPR_TOKEN=${{ secrets.LESCOPR_TOKEN }}" >> $GITHUB_ENV
      - name: Run tests with instrumentation
        run: |
          docker compose up -d lescopr-agent
          pytest -vv

3.2 Configurar GitLab CI

stages:
  - test

test_job:
  stage: test
  image: python:3.11
  variables:
    LESCOPR_TOKEN: $LESCPR_TOKEN
  script:
    - docker run -d -e LESCOPR_TOKEN=$LESCPR_TOKEN lescopr/agent
    - pip install -r requirements.txt
    - pytest -vv

3.3 Correlación en tiempo real

Una vez que los jobs envían trazas y logs, el dashboard de Lescopr permite filtrar por trace_id. Al seleccionar un trace_id fallido, se muestra:

• Métricas de latencia de la prueba.
• Eventos de error capturados por el agente.
• Historial de cambios en el código que afectaron esa traza.

Esta vista unificada convierte un mensaje de error críptico en una historia completa de ejecución.

3.4 Lista de pasos clave para la correlación

• Instrumentar cada test con un trace_id único.
• Enriquecer los logs estructurados con el mismo trace_id.
• Configurar los pipelines para exportar trazas a Lescopr.
• Crear dashboards que filtren por trace_id y muestren métricas APM.
• Alertar cuando la tasa de flaky tests supere el umbral definido.

4. Validación y monitoreo continuo

4.1 Pruebas de carga en el pipeline

Ejecuta el pipeline con 100 % de paralelismo y registra:

• Tiempo medio de ejecución por job.
• Overhead introducido por el agente Lescopr (< 3 %).

4.2 Métricas de éxito

Métrica	Valor objetivo
Reducción MTTR	≥ 30 %
Incremento de detección de flaky	≥ 80 %
Overhead de APM	≤ 5 % del tiempo total

4.3 Ajustes finos y trade‑offs

Si el overhead supera el umbral, considera reducir la frecuencia de muestreo o excluir pruebas de bajo riesgo. La observabilidad siempre implica un balance entre detalle y coste.

5. Lanzamiento y siguientes pasos

Con la infraestructura validada, puedes promover la configuración a los entornos de producción. Lescopr ofrece plantillas de SLA dashboards que permiten monitorizar el cumplimiento de los acuerdos de disponibilidad y tiempo de respuesta.

Tip: Usa la función de retención de datos de Lescopr para mantener históricos de 30 días y comparar tendencias de flaky tests a lo largo del tiempo.

---

Para profundizar, la documentación de Lescopr detalla la implementación paso a paso.