Resolució d’incidències habituals en Connectors

Navegació

Resolució d’incidències habituals en Connectors

Canigó – Guia de troubleshooting

Aquesta pàgina recull els errors més freqüents en connectors d’EventHub, les seves causes i com actuar. Està pensada tant per a equips d’aplicacions com per a l’operació.

1. OracleCDC: pèrdua d’offset (ORA-01291)

Símptoma

El connector OracleCDC passa a estat FAILED amb un error similar a:

The connector failed with "ORA-01291: missing log file".
Not all log files corresponding to the SCN range [XXXXXXXXXX - XXXXXXXXXX]
specified had been added to the LogMiner session.

Causa

El connector ha perdut el punt de lectura en els redo logs d’Oracle. Pot passar per:

• Logs d’Oracle que han rotat abans que el connector els llegís.
• Connector aturat durant un temps prolongat.
• Intervenció en la BBDD que hagi eliminat logs anteriors.

Resolució

1. Escalar al projecte propietari de la BBDD.
2. Indicar-los:
   • Nom del connector.
   • BBDD afectada.
   • El primer SCN que indica l’error.
3. Sol·licitar que BBDD restauri els logs per cobrir el moment de l’error.
4. Un cop restaurats els logs, reiniciar el connector.

Entorns no productius (INT/PRE)

Si no és crític perdre dades, es pot resoldre afegint la propietat:

"start.from": "force_current"

Això fa que el connector reprengui des del moment actual, descartant el històric perdut.

2. MongoSource: pèrdua d’OPLOG

Símptoma

El connector MongoSource passa a estat FAILED amb un error:

"errmsg": "Resume of change stream was not possible, as the resume point
may no longer be in the oplog."
"codeName": "ChangeStreamHistoryLost"

Causa

L’oplog de MongoDB ha rotat i el connector no pot reprendre des del punt on es va aturar. Pot passar per:

• Intervenció en la BBDD que elimini l’oplog anterior.
• Connector aturat o fallat durant un temps prolongat.
• Volum molt alt de canvis que fa rotar l’oplog ràpidament.

Resolució

1. Notificar al projecte propietari de la BBDD.
2. Sol·licitar la restauració de l’oplog al moment de la caiguda.
3. Un cop restaurat, reiniciar el connector.

Workaround (si no es pot restaurar l’oplog)

Si el projecte accepta possible reordenació de dades:

1. Configurar el connector per descartar el històric i reprendre des de l’actual, seguint la guia de MongoDB.
2. Coordinar amb el projecte per fer un update massiu dels documents afectats (ex: sumar 1ms a un camp timestamp) per forçar que arribin al topic.
3. L’aplicació destí ha de validar els datos rebuts.

⚠️ Requereix coordinació entre EventHub, BBDD i l’aplicació consumidora.

3. Errors SSL en connectors (INT/PRE)

Símptoma

El connector falla amb errors de SSL handshake o connection reset.

Causa habitual

El certificat JKS del client s’ha renovat recentment i el connector no l’ha carregat correctament.

Resolució

1. Reiniciar el connector des del Control Center o l’autoservei GEH.
2. Esperar 5 minuts i comprovar l’estat.
3. Si funciona correctament, l’error era temporal per la renovació del certificat.

Si persisteix l’error

El JKS pot haver caducat:

1. Comprovar la caducitat del certificat.
2. Si ha caducat, sol·licitar al projecte que generi un nou certificat seguint la guia de renovació.
3. Un cop generat, obrir tiquet per pujar-lo als Connect de l’entorn afectat.

4. Errors de BBDD externa

Símptoma

El connector (habitualment un Sink) falla amb errors que referencien la base de dades destí: connexió refusada, timeouts, errors d’esquema de taula, etc.

Causa

El problema és extern a EventHub: la BBDD destí pot estar caiguda, sense comunicació, o amb canvis d’esquema no compatibles.

Resolució

1. Posar en pausa el connector (no eliminar-lo).
2. Notificar al projecte propietari de la BBDD indicant l’error.
3. Esperar a que es resolgui la incidència amb la BBDD.
4. Un cop resolta, reprendre el connector.

⚠️ No eliminar el connector: la pausa preserva l’estat i els offsets.

5. Error amb el topic intern del schema

Símptoma

El connector falla amb un error relacionat amb el topic intern de Schema Registry.

Resolució

1. Eliminar el connector.
2. Canviar el nom del connector afegint un comptador de versió (ex: -v1.0.1).
3. Tornar a pujar el connector amb el nou nom.

6. Reset d’offsets de consumer groups

Quan és necessari

Quan cal que un connector Sink o una aplicació consumidora reprengui el consum des d’un punt concret (ex: després d’una incidència, per reprocessar dades).

Dades necessàries

• Topic: consultar la configuració del connector Sink o demanar-ho a l’aplicació.
• Consumer group: habitualment connect-<nom_connector> per a connectors.
• Offset: determinar-lo utilitzant el consumer del Control Center amb filtre de data.

Comanda

kafka-consumer-groups --bootstrap-server "<bootstrap-server>" \
  --topic <topic> \
  --group <consumer_group> \
  --reset-offsets --to-offset <offset>

⚠️ Executar primer sense --execute per simular el canvi. Afegir --execute només quan es confirmi que és correcte.

⚠️ Es necessita un comanda per cada combinació de topic i partició. Format: <topic>:<particio>.

7. Quan escalar

Vegeu també

• Ús de Connectors
• Observabilitat
• Incidències transversals
• CRQ d’urgència