connect-cdc

Runbook — Connect CDC

Los 10 incidentes más frecuentes en operación de Connect CDC (Precisely), con síntoma, evidencia, primer paso y criterio de escalado.

Soporte L1Soporte Senior

Runbook — Connect CDC

Estructura: síntoma, evidencia, diagnóstico inicial (L1), criterio de escalado.

Convenciones: ⚠️ = acción que puede afectar producción.

RB-CDC-001 — Pipeline detenido / no captura cambios

Síntoma

Lag entre source IBM i y destino crece sin freno. La consola muestra el pipeline "stopped" o "stalled".

Evidencia a recolectar

Flujo de diagnóstico inicial (L1)

  1. •

    Verificar el estado del pipeline en la Management Console.

    Navegar a: Management Console → Pipelines → [nombre del pipeline] → El estado se muestra en la columna Status. Los valores posibles son Running, Stopped, Error, Starting, Stopping. Si dice Error, el panel inferior muestra el último mensaje de error — copiarlo completo antes de cualquier acción.

  2. •

    Verificar si el agente IBM i está activo.

    WRKACTJOB JOB(CDC*)

    → Buscar el job del agente CDC (el nombre exacto varía por instalación; consultar documentación del cliente). Debe estar en status ACTIVE. Si no aparece o está en MSGW, ese es el problema primario.

    WRKACTJOB SBS(CDCSBSYS)

    → Reemplazar CDCSBSYS con el nombre real del subsystem de Connect en el cliente. Todos los jobs del agente deben aparecer con status RUN o DEQW.

  3. •

    Verificar el joblog del agente para mensajes de error.

    DSPJOBLOG JOB(nombre_job_agente_cdc)

    → Buscar mensajes con severidad 30 o mayor. Los mensajes de Connect CDC comienzan típicamente con prefijo CDC o el propio del producto. Copiar el texto completo del error.

  4. •

    Verificar conectividad del agente hacia el motor Connect.

    PING RMTSYS('ip_del_servidor_motor_connect')

    → Si no responde, la conectividad de red está rota — escalar a redes y al senior simultáneamente.

  5. •

    Buscar mensaje de error específico en QSYSOPR.

    WRKMSG MSGQ(QSYS/QSYSOPR) SEQ(*NEW)

    → Filtrar por la franja temporal del incidente. Buscar mensajes relacionados con comunicaciones TCP, journaling, o mensajes del subsystem CDC.

Criterio de escalado

RB-CDC-002 — Tabla nueva no journaled (no se captura)

Síntoma

Una tabla recién creada en producción IBM i no aparece en el destino. Sin error explícito; simplemente "no llega".

Evidencia a recolectar

Flujo de diagnóstico inicial (L1)

  1. •

    Confirmar que la tabla no está journaled o está journaled con imagen incorrecta.

    DSPFD FILE(MILIB/MITABLA)

    → Buscar la sección "Journaling information". El campo Journaled debe decir Yes. El campo Journal images debe decir *BOTH (Connect CDC requiere imágenes AFTER para capturar el valor nuevo, y BEFORE cuando el destino necesita reconstruir el before-image). Si dice *AFTER solamente o *BEFORE solamente → ver RB-CDC-003. Si dice No → la tabla no está journaled y no se captura.

  2. •

    Confirmar si la tabla está dentro del scope del pipeline.

    En la Management Console: Pipelines → [pipeline] → Source → Tables → Verificar si la tabla aparece en la lista de objetos monitoreados. Si no aparece, puede ser por scope de biblioteca, filtro de nombre, o que el pipeline fue configurado antes de que existiera la tabla.

  3. •

    Notificar al equipo de aplicación.

  4. •

    ⚠️ Iniciar journaling solo bajo procedimiento aprobado.

    STRJRNPF FILE(MILIB/MITABLA) JRN(MILIB/MIJRN) IMAGES(*BOTH) OMTJRNE(*OPNCLO)

    → Confirmar con DSPFD FILE(MILIB/MITABLA) que ahora Journaled dice Yes y Journal images dice *BOTH.

Criterio de escalado

(Fuente: Precisely Help — Set up journaling)

RB-CDC-003 — Imagen de journal incorrecta (BEFORE only)

Síntoma

Pipeline reporta error de captura por imagen incompleta. Updates llegan al destino sin valores nuevos o sin valores viejos según el caso.

Evidencia a recolectar

Flujo de diagnóstico inicial (L1)

  1. •

    Confirmar la imagen de journaling activa.

    DSPFD FILE(MILIB/MITABLA)

    → El campo Journal images debe decir *BOTH. Si dice *BEFORE o *AFTER solamente, hay que corregirlo. Connect CDC requiere *BOTH para la mayoría de los destinos.

  2. •

    Verificar la configuración del journal para entender la política general.

    DSPJRN JRN(MILIB/MIJRN)

    → La imagen por defecto del journal puede estar configurada diferente a la del archivo individual. Documentar ambos valores.

  3. •

    Documentar y notificar al senior — el cambio de imagen requiere coordinación.

  4. •

    ⚠️ Cambiar la imagen requiere ENDJRNPF + STRJRNPF con la imagen correcta — coordinar ventana con aplicación.

    ENDJRNPF FILE(MILIB/MITABLA) JRN(MILIB/MIJRN)
STRJRNPF FILE(MILIB/MITABLA) JRN(MILIB/MIJRN) IMAGES(*BOTH)

    → El intervalo entre ENDJRNPF y STRJRNPF no se captura — debe coordinarse con el equipo de aplicación para que no haya transacciones en esa ventana.

Criterio de escalado

RB-CDC-004 — Authentication / authorization error contra destino

Síntoma

Pipeline reporta error tipo "authentication failed", "401", "invalid credentials" hacia Snowflake / Kafka / SQL Server / Oracle / etc.

Evidencia a recolectar

Flujo de diagnóstico inicial (L1)

  1. •

    Verificar el mensaje de error exacto en la Management Console.

    Navegar a: Management Console → Pipelines → [pipeline] → Logs → El mensaje de error del destino aparece en los logs del motor. Buscar entradas con nivel ERROR o FATAL. El mensaje incluye el código de error del destino (ej. 401 Unauthorized, JDBC authentication failed, SASL authentication failed).

  2. •

    Verificar si hubo rotación de credenciales / certificados reciente. → Consultar al equipo del destino cuándo fue la última rotación. Si fue reciente, ese es el origen probable.

  3. •

    Verificar conectividad de red al destino.

    PING RMTSYS('ip_o_hostname_destino')

    → Si no responde, el problema es de red, no de autenticación. Escalar a redes.

  4. •

    Notificar al equipo dueño del destino (DBAs / data engineering).

Criterio de escalado

RB-CDC-005 — Lock / DDL en tabla destino impide aplicar

Síntoma

Pipeline aplica algunos cambios y luego se detiene en una tabla específica con error de lock o DDL incompatible.

Evidencia a recolectar

Flujo de diagnóstico inicial (L1)

  1. •

    Identificar la tabla destino desde los logs de Connect.

    En la Management Console: Pipelines → [pipeline] → Logs → El error incluye el nombre de la tabla destino y el tipo de error (lock timeout, DDL error, constraint violation). Anotar exactamente.

  2. •

    Si el destino es IBM i, verificar lock activo sobre la tabla destino.

    WRKOBJLCK OBJ(MILIB/MITABLA) OBJTYPE(*FILE)

    → Si hay locks *EXCL o *EXCLRD, algún job tiene el objeto bloqueado. Anotar el job que tiene el lock.

  3. •

    Identificar si hubo cambio DDL reciente en destino (columna agregada, tipo cambiado, índice nuevo). → Consultar al equipo de aplicación/DBA del destino. Un cambio DDL no coordinado con Connect CDC es la causa más común.

  4. •

    Notificar al equipo del destino.

Criterio de escalado

RB-CDC-006 — Mapping mismatch (columna nueva en source)

Síntoma

Source agregó una columna nueva. El pipeline o no la replica, o falla al intentar aplicarla en destino.

Evidencia a recolectar

Flujo de diagnóstico inicial (L1)

  1. •

    Confirmar la columna nueva en source.

    DSPFFD FILE(MILIB/MITABLA)

    → Lista todos los campos del archivo con sus atributos (tipo, longitud, nulo). Comparar con el schema configurado en el mapping del pipeline.

  2. •

    Confirmar mapping vigente en pipeline.

    En la Management Console: Pipelines → [pipeline] → Mappings → [tabla] → El mapping muestra columnas de source mapeadas a columnas de destino. Si la columna nueva del source no aparece, el pipeline la ignora. Si aparece pero el destino no tiene la columna correspondiente, el pipeline fallará al intentar aplicar.

  3. •

    Notificar al equipo de aplicación + data engineering para coordinar el schema change en destino.

Criterio de escalado

RB-CDC-007 — Cola IBM i Data Queue saturada

Síntoma

Backlog en la Data Queue intermedia entre el agente CDC y el motor. Lag crece. Storage en IBM i empieza a presionar.

Evidencia a recolectar

Flujo de diagnóstico inicial (L1)

  1. •

    Verificar el estado y tamaño de la Data Queue.

    WRKDTAQ DTAQ(MILIB/CDC_DTAQ)

    → Reemplazar CDC_DTAQ con el nombre real de la data queue del producto (consultar documentación de instalación del cliente). La pantalla muestra el número de mensajes en cola y el tamaño máximo configurado. Si la cola está cerca del máximo, el agente va a empezar a rechazar entradas.

  2. •

    Verificar si el motor Connect está procesando (consumiendo la cola).

    → Si la data queue crece pero el motor no la consume, el problema está del lado del motor o del destino — no del agente IBM i. Verificar el estado del motor en la Management Console.

  3. •

    Verificar disco en IBM i.

    WRKDSKSTS

    → Si el % USED supera el 80%, la data queue puede quedarse sin espacio para crecer. El agente CDC puede empezar a fallar o bloquearse.

Criterio de escalado

RB-CDC-008 — Catch-up imposible tras caída larga

Síntoma

Tras una caída prolongada del pipeline, al reanudar se reporta "cannot resume from offset" o "journal receivers no longer available".

Evidencia a recolectar

Flujo de diagnóstico inicial (L1)

  1. •

    Confirmar receivers disponibles vs offset requerido.

    WRKJRNRCV JRN(MILIB/MIJRN)

    → La lista muestra todos los receivers con su rango de secuencias. Connect CDC necesita que el receiver que contiene la secuencia donde se detuvo el pipeline todavía exista. Si ese receiver fue purgado (estado DLT), el catch-up es imposible.

  2. •

    Identificar la secuencia donde el pipeline se detuvo.

    En la Management Console: Pipelines → [pipeline] → Advanced → Current Position → El número de secuencia de journal se muestra aquí. Comparar con el rango del receiver más viejo disponible.

  3. •

    Documentar la situación completa: receiver requerido, receivers disponibles, gap de tiempo.

  4. •

    Notificar al senior — esto puede requerir re-sincronización completa.

Criterio de escalado

RB-CDC-009 — Performance degradation del destino

Síntoma

Pipeline corre pero con lag creciente. El bottleneck es el destino (Snowflake warehouse saturado, Kafka broker lento, base de datos con locks).

Evidencia a recolectar

Flujo de diagnóstico inicial (L1)

  1. •

    Identificar dónde está el bottleneck usando la Management Console.

    Navegar a: Management Console → Pipelines → [pipeline] → Statistics → El panel de statistics muestra throughput por etapa: capture rate (agente IBM i), apply rate (motor hacia destino). Si el capture rate es alto pero el apply rate es bajo, el bottleneck está en el destino.

  2. •

    Si el destino es Kafka, verificar consumer group lag (conceptual — requiere acceso a Confluent Control Center o CLI).

    Referencia Confluent CLI:

    confluent kafka consumer group lag list --cluster [cluster-id] --group [consumer-group-connect-cdc]

    → Un lag de consumer group mayor a 100.000 mensajes indica que el consumidor de Connect CDC no puede procesar a la velocidad que Kafka recibe. Notificar al equipo de data engineering.

  3. •

    Si el destino está claramente saturado: notificar al equipo dueño del destino.

  4. •

    Documentar los números de throughput con timestamps.

Criterio de escalado

RB-CDC-010 — Datos esperados no aparecen en destino (sin error)

Síntoma

Aplicación dice que cierto cambio "se hizo" en source, pero no aparece en destino. No hay error reportado por el pipeline.

Evidencia a recolectar

Flujo de diagnóstico inicial (L1)

  1. •

    Reproducir la query en source para confirmar que el dato existe en IBM i.

    RUNQRY QRYFILE((MILIB/MITABLA)) QRYTEXT('SELECT * FROM MILIB/MITABLA WHERE CAMPO = ''valor''')

    → Si el dato no existe en source, el problema es del lado de la aplicación — la transacción no se completó.

  2. •

    Buscar el cambio en el journal del source.

    DSPJRN JRN(MILIB/MIJRN) RCVRNG(*CURCHAIN) JRNCDE(R) ENTTYP(PT UB RB) FILE((MILIB/MITABLA))

    → ENTTYP(PT) = put/insert, UB = update before, RB = rollback. Si el cambio tiene una entrada de RB (rollback), la transacción fue deshecha — el dato nunca existió de forma permanente. Explicar al equipo de aplicación. Si hay PT o UB sin RB, el cambio está journaled.

  3. •

    Si el cambio SÍ está en journal pero no en destino: escalar.

Criterio de escalado

Anexo — convenciones de escalado a Precisely Support

Cuando se abre un case con Precisely Support, incluir:

Plantilla de comunicación P1

Usar cuando el pipeline está detenido y el impacto en el negocio es crítico (datos de producción que no llegan al destino, SLA de latencia roto, destino sin datos frescos). Enviar por email y por el canal de guardia definido en el contrato del cliente.

ASUNTO: [P1] Connect CDC — [cliente] — Pipeline [nombre] detenido — [timestamp]

CLIENTE: [nombre]
PRODUCTO: Connect CDC v[versión motor] / Agente IBM i v[versión agente]
SOURCE: IBM i [hostname/IP] — Biblioteca(s): [lista]
DESTINO: [Snowflake / Kafka / SQL Server / otro] — [endpoint o cluster]
PIPELINE: [nombre o ID del pipeline]
INICIO DEL INCIDENTE: [fecha y hora con timezone]
DETECTADO POR: [quién detectó — alerta automática / usuario / soporte]

IMPACTO:
- [Describe el impacto: datos no replicados, aplicaciones que dependen del destino, etc.]
- Lag actual: [valor] segundos / minutos
- Última secuencia de journal procesada: [sequence number si está disponible]

ESTADO ACTUAL:
- Estado del pipeline en consola: [Running / Stopped / Error]
- Estado del agente IBM i: [ACTIVE / MSGW / no encontrado]
- Estado del motor Connect: [corriendo / caído]

ACCIONES YA EJECUTADAS:
- [Lista de acciones tomadas y resultados observados]

EVIDENCIA RECOLECTADA:
- [x] Joblog del agente CDC — adjunto
- [x] Logs del motor Connect — adjunto
- [x] QSYSOPR source IBM i — adjunto
- [x] Screenshot del estado del pipeline en consola — adjunto
- [ ] [Lo que aún falta]

PRÓXIMA ACCIÓN:
- Esperando instrucción de [senior / cliente / Precisely Support]

CONTACTO GUARDIA SOPORTE SENIOR: [nombre y celular]
CONTACTO CLIENTE (técnico): [nombre y celular]

Recursos relacionados