Errores silenciosos en la integración de datos: cómo loguear y detectar los que nadie ve

Los datos corruptos que circulan entre sistemas generan costos invisibles. Erwin explica cómo implementar logging de errores en flujos de integración para detectar desvíos antes de que se conviertan en problemas de catálogo, operación o negocio.

Cuando una integración falla de forma evidente, el equipo suele reaccionar rápido. Una API devuelve error, un proceso se corta, un job no termina o aparece una alerta en monitoreo. Son fallos molestos, pero al menos se ven.

El problema más serio suele estar en otro lugar: los errores silenciosos.

Son los que no rompen el flujo completo, pero dejan datos incompletos, inconsistentes o directamente corruptos circulando entre ERP, PIM, DAM, eCommerce o marketplaces. El proceso termina, el script no cae, el lote figura como exitoso y, sin embargo, algo quedó mal.

Ese tipo de error es especialmente peligroso porque se descubre tarde. A veces aparece como un atributo vacío en el PIM. A veces como una variante mal armada en el eCommerce. A veces como una imagen incorrecta, una categoría rota o un producto publicado con información degradada. En todos los casos, el costo ya empezó a correr antes de que alguien note el problema.

En flujos de integración, loguear bien no es un detalle técnico. Es una condición básica para reconstruir qué pasó, dónde pasó, qué entidad quedó afectada y qué parte del proceso necesita corrección.

Por qué los errores silenciosos son más peligrosos que los errores visibles

Un error visible interrumpe. Un error silencioso avanza.

Esa diferencia cambia todo. Cuando el fallo es explícito, el equipo sabe que tiene que intervenir. Cuando no lo es, el dato sigue moviéndose por el ecosistema y el problema se multiplica en cada sistema que lo recibe.

En una integración de producto, eso puede pasar de muchas formas:

• un atributo obligatorio llega vacío y nadie lo bloquea;
• una transformación pisa un valor correcto con otro incorrecto;
• una categoría no encuentra equivalencia y se asigna una por defecto;
• una imagen no coincide con el SKU correcto;
• una variante hereda mal la información del producto padre;
• un lote parcial se marca como exitoso aunque dejó registros afuera.

Nada de eso necesariamente rompe el proceso. Pero todo eso degrada la calidad del dato.

Y en ecosistemas PIM, la calidad del dato no es un tema menor. Precisión, completitud, consistencia, vigencia y conformidad son condiciones básicas para que el catálogo pueda sostener publicación, filtrado, sindicación y operación multicanal.

Qué significa loguear bien en una integración

Loguear bien no es llenar la consola de mensajes. Tampoco es guardar un archivo con texto libre que nadie puede interpretar después. En una integración real, un log útil tiene que aportar contexto.

Eso significa que no debería limitarse a decir “falló la sincronización”. Debería ayudar a responder preguntas concretas:

1. ¿Qué proceso se estaba ejecutando?
2. ¿Qué sistema enviaba datos y cuál los recibía?
3. ¿Qué entidad o registro estaba involucrado?
4. ¿En qué paso exacto ocurrió el problema?
5. ¿Se trató de un error técnico, una validación fallida o una degradación silenciosa?
6. ¿El flujo se detuvo, reintentó o siguió adelante?
7. ¿Qué impacto tuvo sobre el dato?

Cuando un log responde a esas preguntas, deja de ser un mensaje técnico aislado y empieza a convertirse en una pieza de observabilidad.

El primer error: registrar solo excepciones técnicas

Uno de los problemas más comunes en integraciones Node.js es asumir que el logging debe ocuparse solamente de excepciones duras: errores 500, fallos de red, timeouts, problemas de autenticación o respuestas inválidas.

Ese tipo de errores importa, pero no alcanza.

Una integración puede devolver 200 y aun así salir mal. Puede aceptar un payload con campos vacíos, truncar valores, omitir registros o transformar mal una unidad sin disparar una excepción. Si el logging solo mira fallos de ejecución, deja afuera el problema más costoso: el dato que se degradó sin romper el proceso.

Por eso conviene pensar el logging en tres niveles:

1. Errores técnicos, como conectividad, autenticación, timeouts o caídas de servicios.
2. Errores de validación, como campos obligatorios ausentes, identificadores mal formados o reglas de negocio incumplidas.
3. Errores silenciosos de contenido, donde el proceso sigue, pero el dato pierde calidad o coherencia.

Ese tercer grupo es el que más cuesta detectar si no fue diseñado de antemano.

Qué debería incluir cada log

Para que el logging sirva de verdad, cada evento registrado debería contener un mínimo de contexto estable. No hace falta volverlo excesivo, pero sí consistente.

Un esquema razonable debería incluir:

• fecha y hora del evento;
• nivel del log;
• nombre del servicio o integrador;
• nombre del flujo;
• sistema origen;
• sistema destino;
• tipo de entidad;
• identificador de entidad;
• identificador de lote o ejecución;
• paso del proceso;
• mensaje descriptivo;
• código de error, si aplica;
• resumen del payload o del cambio detectado;
• identificador de correlación.

Ese último punto es especialmente importante. El identificador de correlación permite seguir un mismo registro, lote o ejecución a través de distintas etapas y distintos sistemas. Sin eso, cada log queda aislado. Con eso, se puede reconstruir el recorrido completo del dato.

Por qué conviene usar logging estructurado

En integraciones medianas o grandes, el texto libre se vuelve insuficiente bastante rápido. Sirve para leer mensajes puntuales, pero complica mucho filtrar, agrupar y detectar patrones.

Por eso conviene trabajar con logging estructurado. La idea es registrar eventos como objetos con campos previsibles y no solo como frases narrativas. Eso facilita búsquedas, dashboards, alertas y análisis posteriores.

Desde el lado técnico, esto además tiene otra ventaja: separa mejor el contenido humano del contenido máquina. El mensaje puede seguir siendo legible, pero los campos importantes quedan disponibles para filtros, métricas y correlación.

En otras palabras, el log deja de ser una línea suelta y pasa a ser una unidad de información operable.

Qué eventos conviene registrar en una integración

No todo merece el mismo nivel de detalle, pero hay hitos que conviene loguear casi siempre.

Inicio y cierre de ejecución

Cada job o flujo debería dejar al menos una marca de inicio y una de cierre. Eso permite saber cuándo arrancó, con qué parámetros corrió, cuántos registros debía procesar y cómo terminó.

Eventos por etapa

Si el flujo tiene extracción, validación, transformación y publicación, cada etapa debería registrar su estado. Eso ayuda a identificar dónde empezó a desviarse el proceso.

Registros con anomalías

No siempre hace falta loguear cada entidad procesada. Pero sí conviene registrar cada una que:

• falle una validación crítica;
• quede descartada;
• se publique parcialmente;
• cambie por fallback;
• pierda un atributo obligatorio;
• o requiera reintento.

Decisiones automáticas del integrador

Este punto es clave y suele olvidarse. Si el proceso decide por su cuenta usar una categoría por defecto, ignorar un asset inválido, truncar un texto o reemplazar un valor fuera de vocabulario, eso debería quedar registrado. Si no queda rastro, el dato cambia y nadie sabe por qué.

Cómo detectar los errores que no generan caída

Tener logs no garantiza detectar errores silenciosos. Para eso hay que definir señales específicas que ayuden a ver desvíos aunque el job termine.

1. Validaciones con niveles de severidad

No todas las anomalías tienen el mismo peso. Conviene clasificar al menos entre:

• error, cuando el registro no debería avanzar;
• warning, cuando puede avanzar pero con riesgo;
• info, cuando se trata de un evento normal del proceso.

Esta clasificación evita dos extremos igual de malos: bloquear todo por cualquier detalle o dejar pasar cualquier cosa sin distinción.

2. Control por lote

Un job puede terminar sin caerse y aun así haber salido mal. Por ejemplo, si el 15% de los productos quedó sin imágenes o si una porción importante perdió categoría durante el mapping.

Por eso conviene medir resultados por lote:

• registros recibidos;
• registros válidos;
• registros rechazados;
• registros con warning;
• registros publicados;
• registros omitidos.

Cuando esas cantidades no cierran, suele haber un problema silencioso escondido en el flujo.

3. Comparación entre entrada y salida

Una de las formas más simples y útiles de detectar degradación es comparar lo que entró con lo que realmente salió.

Ese contraste permite responder preguntas como estas:

• ¿Entraron 1.000 productos y se publicaron 1.000?
• ¿Cuántos se transformaron correctamente?
• ¿Cuántos quedaron con datos incompletos?
• ¿Cuántos se descartaron y por qué?

Cuando no existe esa comparación, el éxito del flujo se mide solo por si el job terminó. Y eso suele ser insuficiente.

4. Contexto de negocio dentro del log

Saber que falló un proceso llamado productSync ayuda poco si no sabemos qué producto, qué familia, qué proveedor o qué canal estaba involucrado.

En integraciones de catálogo, el logging útil necesita hablar tanto el idioma técnico como el de negocio. Ahí es donde el log deja de servir solo al developer y empieza a servir también a operación, catálogo o data stewardship.

5. Dashboards para ver tendencias, no solo incidentes

En varios proyectos de CRITERIA, las integraciones no quedaron solo como scripts ejecutándose en segundo plano. Se acompañaron con dashboards y monitoreo para seguir el resultado del proceso y revisar qué estaba pasando en cada corrida. Ese enfoque es especialmente útil porque muchos problemas de integración no aparecen como un incidente puntual, sino como una degradación progresiva del dato.

Errores silenciosos típicos que conviene modelar

Hay ciertos patrones que se repiten mucho en integraciones de datos de producto. Vale la pena tratarlos como eventos de primera clase en el logging.

Entre los más comunes están estos:

1. producto publicado sin un atributo obligatorio;
2. variante creada sin herencia correcta del padre;
3. categoría no encontrada y reemplazada por una categoría default;
4. imagen referenciada pero inexistente en destino;
5. valor convertido con fallback por no cumplir formato esperado;
6. duplicado detectado, pero flujo continuado;
7. texto truncado para cumplir límites de canal;
8. payload aceptado por API, pero con warnings de negocio;
9. registro omitido por mapping incompleto;
10. lote parcial marcado como exitoso.

Todos esos casos tienen algo en común: no siempre rompen el proceso, pero sí afectan la integridad del dato.

Qué decisiones técnicas ayudan en Node.js

En Node.js, hay varias decisiones concretas que mejoran mucho la capacidad de observación de una integración.

Usar un logger consistente

Apoyarse solo en console.log sirve para pruebas rápidas, pero se queda corto en producción. Conviene usar una librería que permita niveles, estructura y salida consistente. Lo importante no es la herramienta en sí, sino que el logging no quede disperso y desordenado.

Separar el logging del procesamiento pesado

En flujos con mucho volumen, registrar demasiado o hacerlo mal puede afectar el rendimiento. Por eso conviene diseñar el logging para que acompañe al proceso sin convertirse en cuello de botella.

Documentar el esquema de eventos

No alcanza con emitir logs. También conviene definir qué campos existen, qué significan y cómo deben interpretarse. Eso evita que cada parte del integrador escriba eventos de forma distinta.

Conservar contexto para análisis posteriores

Cuando un error serio aparece, muchas veces ya pasó el momento exacto del incidente. Si no quedó contexto suficiente, hacer diagnóstico después se vuelve lento y costoso. Por eso conviene registrar información suficiente para reconstruir el caso incluso tiempo después.

Qué conviene evitar

Hay varias prácticas que vuelven inútil un sistema de logging aunque “registre cosas”.

Las más comunes son:

• loguear solo strings sin contexto;
• registrar errores sin entityId, batchId o flow;
• usar el mismo mensaje para problemas distintos;
• marcar un lote como exitoso aunque tenga demasiados warnings;
• registrar demasiado ruido irrelevante y esconder lo importante;
• no separar errores técnicos de errores de datos;
• no loguear decisiones automáticas del proceso;
• no correlacionar eventos entre sistemas.

Cuando pasa eso, los logs existen, pero no ayudan a operar ni a diagnosticar.

La diferencia entre tener logs y tener observabilidad

Muchas integraciones “tienen logs” porque escriben mensajes durante la ejecución. Pero eso no significa que tengan observabilidad.

La diferencia está en otra parte. Una integración observable no solo deja rastros; deja rastros útiles para entender cuándo el dato empezó a desviarse, qué decisión automática se tomó, qué registro quedó comprometido y cómo se propagó el problema entre sistemas.

Eso es especialmente importante en ecosistemas donde ERP, PIM, DAM, eCommerce y marketplaces intercambian información constantemente. Cuando la degradación del dato no se detecta a tiempo, el problema deja de ser técnico y se convierte en un costo operativo.

Los errores silenciosos son peligrosos porque no interrumpen: avanzan. Y justamente por eso, en integraciones de datos, loguear bien no consiste solo en registrar fallos técnicos. Consiste en construir contexto para detectar degradaciones, seguir el recorrido de cada entidad y entender cuándo una integración dejó de mover datos confiables aunque el proceso siguiera “funcionando”. Ahí está la diferencia entre correr jobs y realmente gobernar el dato.