Solución de problemas del agente privado de Jitterbit

Esta página proporciona orientación para solucionar problemas comunes al instalar, ejecutar o administrar un agente privado de Jitterbit. Comienza con los pasos de diagnóstico a continuación, luego busca tu error específico en la sección correspondiente. Contacta al soporte de Jitterbit para problemas no listados aquí.

Para una referencia unificada que cubra problemas de integración, automatización, gestión de API, EDI y desarrollo de aplicaciones en un solo lugar, consulta la guía de solución de problemas de Harmony.

• Observabilidad

  -   [La observabilidad nativa no muestra datos](#observability-no-data)
  -   [Faltan métricas del agente cuando el agente se conecta a través de un proxy HTTP](#metrics-proxy)
  -   [El agente de Datadog no se inicia después de la instalación de Docker](#datadog-docker)
  

  • Problemas del sistema y del SO

    • Error del servidor Apache: No hay ConfigArgs instalado
    • Apache/Tomcat: APPARENT DEADLOCK
    • Apache se bloquea inesperadamente bajo carga concurrente
    • El servicio de limpieza no puede eliminar archivos de registro bloqueados en Windows
    • Linux: Los servicios del agente no se inician después de un reinicio ("postmaster.pid no existe")
    • Linux: El antivirus elimina PgBouncer y el agente no se autentica en la base de datos incluida
    • Los análisis de seguridad marcan log4j-over-slf4j.jar como una vulnerabilidad de Log4j 1.x

  • Docker

    • General
    • El agente no se reinicia con errores de autenticación después de la anulación del registro

  • Servicio de escucha

    • "El clúster no ha alcanzado el tamaño mínimo requerido"
    • Los mensajes del servicio de escucha no se entregan

  • Registro

    • Los registros de operación de API personalizados no aparecen
    • El registro de depuración de operación se detiene antes de la fecha de finalización seleccionada
    • Faltan datos .input o .output en los archivos de registro de depuración de operación
    • Los datos de entrada/salida del componente no se generan

Pasos de diagnóstico

Estos pasos son el punto de partida recomendado para la mayoría de los problemas del agente privado.

Verificar el estado del agente

Revisa el estado actual del agente en la Consola de administración en Agentes > Privado, luego úsalo para reducir el problema. Para las definiciones de estado completas y cómo hacen la transición, consulta Estado del agente.

Verificar los archivos de registro del agente

Los archivos de registro del agente son la fuente principal de información de diagnóstico. Verifica el siguiente archivo para detectar errores relacionados con la conectividad, la salud del servicio y los fallos de operación:

• Windows: C:\Program Files\Jitterbit Agent\log\jitterbit-agent.log
• Linux: /opt/jitterbit/log/jitterbit-agent.log

Para obtener una lista completa de los archivos de registro disponibles, consulta Registros del agente.

Usar las herramientas de soporte del agente

Las herramientas de soporte del agente proporcionan comandos de diagnóstico que se ejecutan directamente en el host del agente:

• connection-check: Verifica la conectividad desde el agente hacia la nube de Harmony, Apache y los servicios de Tomcat.
• service-status: Muestra el estado de ejecución de todos los servicios del agente (Apache, Tomcat, PostgreSQL, PgBouncer, VerboseLogShipper).
• generate-report: Crea un reporte HTML de diagnóstico y un archivo ZIP con todos los archivos de registro del agente, útil al escalar a soporte de Jitterbit. En agentes Linux, el reporte actualmente omite datos de PostgreSQL; los agentes Windows no se ven afectados.

Para acceder a las herramientas:

cd /opt/jitterbit/AgentSupportTools
./run.sh

cd "C:\Program Files\Jitterbit Agent\AgentSupportTools"
.\run.bat

Reiniciar el agente

Muchos problemas transitorios (cachés de enrutamiento obsoletos, agotamiento de grupos, condiciones de bloqueo) se resuelven con un reinicio del servicio:

• Windows: Iniciar o reiniciar el agente
• Linux: Iniciar o reiniciar el agente

Estado del agente y conectividad

Agente sin conexión o inaccesible

• Síntoma: La pestaña Privado de la página Agentes de la Consola de Administración muestra el agente como Desconocido o Detenido, o Studio muestra un error Agent Not Running or Unreachable.

• Posibles causas:

  • Los servicios de Jitterbit no se están ejecutando.
  • Los servicios se están ejecutando pero el host del agente no puede alcanzar la nube de Harmony.
  • Un proxy corporativo está impidiendo que el agente se conecte.

• Resolución:

  • Si los servicios de Jitterbit no se están ejecutando, inícialos:

    • Windows: Consulta Iniciar un agente Windows.
    • Linux: Consulta Iniciar un agente Linux.

    Si el servicio no se inicia, verifica lo siguiente para buscar mensajes de error:

    • Windows: C:\Program Files (x86)\Jitterbit Agent\log y el registro de Visor de eventos de Aplicación de Windows.
    • Linux: /opt/jitterbit/log.

    La cuenta que ejecuta los servicios de Jitterbit requiere derechos de administrador local en Windows y acceso completo al directorio de instalación de Jitterbit.

  • Si los servicios se están ejecutando pero no pueden alcanzar la nube de Harmony, verifica lo siguiente:

    • La conectividad a Internet desde el host del agente funciona.
    • El registro del agente (jitterbit-agent.log) no contiene mensajes de error sobre conectividad en la nube.
    • El agente puede alcanzar el portal de Harmony en el puerto 443.

  • Si el agente se conecta a través de un proxy corporativo, verifica que el proxy esté configurado correctamente para el agente, incluyendo el dominio NTLM si el proxy utiliza autenticación NTLM. Consulta Servidor proxy para agentes privados de Jitterbit. El registro de denegación del servidor proxy es útil para diagnosticar qué está bloqueando el proxy.

  • Si los servicios del agente están en buen estado en el host (jitterbit status muestra todos los servicios en ejecución) pero el agente cambia repetidamente a Desconocido, o alterna entre En ejecución, Desconocido y Detenido, es probable que la conexión o el proceso del agente se interrumpa entre latidos. Verifica las siguientes posibles causas:

    • Un dispositivo de red (firewall, puerta de enlace NAT o tiempo de inactividad de VM en la nube) puede estar cerrando la conexión saliente del agente entre latidos. Intenta reducir el intervalo de latido del agente (agent.heart.beat.interval). Para agentes alojados en la nube, consulta Azure VM: Conexiones perdidas y errores de WebSocket/I/O, que también se aplica a otras redes restringidas como AWS.
    • El agente puede haber fallado bajo presión de memoria. Busca archivos de volcado de crash OutOfMemoryError o hs_err_pid. Consulta Espacio de heap de Java: OutOfMemoryError.
    • Si los agentes se migraron recientemente a un nuevo sistema operativo mientras se reutilizaba un grupo de agentes que anteriormente alojaba agentes en el SO anterior, el grupo reutilizado puede ser la causa. Consulta El agente muestra Desconocido o Detenido después de reutilizar un grupo de agentes en sistemas operativos.

El agente muestra diferentes versiones o direcciones IP

• Síntoma: La pestaña Privado de la página Agentes de la Consola de Administración muestra diferentes versiones o direcciones IP para un agente privado, o los valores cambian de un lado a otro después de reiniciar los servicios.
• Causa posible: Es posible que la máquina host del agente se haya duplicado a nivel de infraestructura (por ejemplo, un clon de VM, imagen de disco, plantilla de máquina o snapshot creado después de que se instaló y registró el agente). El host duplicado lleva las mismas credentials.txt del agente, por lo que ambos hosts se autentican en Harmony como el mismo agente y se ejecutan en paralelo, colisionando. Dos agentes no pueden ejecutarse simultáneamente bajo las mismas credenciales.
• Resolución:
  1. Confirma que se está ejecutando un duplicado. Detén el agente en el host que deseas mantener, espera 10 minutos y luego actualiza la pestaña Privado de la página Agentes de la Consola de Administración. Si el agente cambia de Detenido a En ejecución, otro host se está reportando bajo la misma identidad.
  2. Identifica y apaga el host duplicado.
  3. Si no se puede apagar el duplicado, desinstala el agente, crea un nuevo agente con un nombre diferente y reinstálalo en el host que deseas mantener.
  4. Verifica que el nuevo agente aparezca como En ejecución en la pestaña Privado de la página Agentes de la Consola de Administración.
  5. Elimina la entrada del agente anterior usando Acciones > Eliminar.

El agente muestra Desconocido o Detenido después de reutilizar un grupo de agentes en diferentes sistemas operativos

• Síntoma: Después de migrar agentes privados a un sistema operativo diferente (por ejemplo, de Windows a Linux) mientras se reutiliza el mismo grupo de agentes, los agentes migrados muestran intermitentemente Desconocido o Detenido en la pestaña Privado de la página Agentes de la Consola de Administración, aunque jitterbit status muestre que los servicios se están ejecutando y las operaciones funcionan normalmente.
• Causa posible: Reutilizar un grupo de agentes del sistema operativo anterior puede dejar metadatos que interfieran con la generación de reportes de estado para los nuevos agentes. El efecto es típicamente cosmético: los servicios y operaciones continúan ejecutándose normalmente.
• Resolución: Crea un nuevo grupo de agentes limpio para los agentes migrados en lugar de reutilizar el grupo del sistema operativo anterior, luego registra los agentes allí.

Falla de sincronización del agente: Los cambios del proyecto no se aplican

• Síntoma: Después de implementar cambios en Studio, el agente continúa ejecutando la versión anterior del proyecto, o una operación falla porque no se encuentra una conexión recién agregada en el agente.

• Causas posibles:

  • La implementación utilizó Implementación Configurable, que implementa solo los flujos de trabajo y operaciones seleccionados. Cualquier parte del proyecto fuera de esa selección permanece en su versión implementada anteriormente en el agente.
  • El componente no se utiliza en el flujo lógico de un flujo de trabajo implementado. Los componentes no utilizados no se implementan, por lo que una conexión que ninguna operación implementada referencia no se envía al agente.
  • Ocurrió un tiempo de espera de red o un error de autorización durante la sincronización.
  • El espacio en disco bajo en el host del agente impidió que se escribieran los archivos del proyecto sincronizados.

• Resolución:

  • Vuelve a implementar el proyecto completo: en Studio, utiliza Implementar, que implementa todas las operaciones del proyecto, en lugar de una Implementación Configurable de solo flujos de trabajo u operaciones seleccionados.
  • Reinicia los servicios del agente para forzar una sincronización nueva de todos los proyectos implementados.
  • Revisa los registros del agente para tiempos de espera de red relacionados con la sincronización o errores de autorización.
  • Verifica el espacio en disco disponible en el host del agente. Un disco lleno o casi lleno puede impedir que el agente escriba archivos de proyecto sincronizados. Consulta Espacio en disco y acumulación de registros.

Operaciones retrasadas o en cola después de desplegar un proyecto

• Síntoma: Después de desplegar un proyecto en Studio, las operaciones activadas no se inician inmediatamente, o aparece un breve acumulamiento de operaciones en cola.
• Causa: El entorno se bloquea mientras el agente sincroniza el proyecto desplegado. No se puede ejecutar ninguna operación durante este período.
• Resolución:
  1. Para medir cuánto tiempo duran los bloqueos de sincronización, busca environment-deploy en jitterbit-agent.log. Cada entrada de registro incluye el ID del entorno y la duración de la sincronización en milisegundos.
  2. Los tiempos de sincronización consistentemente largos indican un proyecto grande o conectividad lenta a Harmony. Para reducir los tiempos de sincronización, consulta ajuste de rendimiento de sincronización del entorno.
  3. Si las duraciones de sincronización son consistentemente excesivas (más de unos pocos minutos), contacta con soporte de Jitterbit.

Agente que se muestra como incapaz

• Síntoma: Las operaciones enviadas al grupo de agentes se reintentan o se retrasan en lugar de ejecutarse inmediatamente. ProcessEngine.log contiene mensajes repetidos como:

  Agent (Id: ...) is incapable to process this message. Message will be auto-retried.
  

  Capability status changed from true to false
  

• Posibles causas:

  • Todos los hilos de trabajo en el motor de procesos del agente ya están en uso, por lo que el agente no puede aceptar otra operación hasta que se libere un hilo. El tamaño del grupo se establece mediante MaxNumberOfWorkerThreads en la sección [ProcessEngine] de jitterbit.conf.
  • Una métrica de capacidad opcional está habilitada y ha alcanzado su umbral. El uso de CPU, el uso de memoria y el uso de hilos de Apache pueden contribuir al estado de capacidad, pero los tres están deshabilitados de forma predeterminada y se aplican solo cuando se activan en la sección [AgentCapability] de jitterbit.conf. El uso de memoria se recopila solo en agentes Windows, por lo que no contribuye al estado de capacidad en un agente Linux incluso cuando la configuración de memoria está habilitada. Apache solo sirve solicitudes de API, por lo que el uso de hilos de Apache es relevante solo en un agente que maneja APIs.
  • Un único agente en el grupo está manejando más carga de la que puede sostener mientras otros agentes en el grupo están inactivos o subutilizados.

• Resolución: Revisa ProcessEngine.log para encontrar secuencias largas de cambios de estado de capacidad para confirmar que el agente alterna entre estados capaz e incapaz, luego investiga lo siguiente:

  • Si muchas operaciones se ejecutan consistentemente a la vez, revisa MaxNumberOfWorkerThreads en la sección [ProcessEngine] de jitterbit.conf. Aumentar este valor permite más operaciones concurrentes pero también aumenta la demanda de CPU y memoria, así que establécelo de forma conservadora.
  • Determina qué métricas de capacidad están habilitadas en la sección [AgentCapability]. Si ninguna está habilitada, la carga de CPU y memoria no es lo que cambió el estado de capacidad del agente, y la disponibilidad de hilos es el factor más probable. Si el uso de CPU o memoria está habilitado, verifica esto antes que las métricas de hilos: si cualquiera de ellos cruza su umbral, el agente se vuelve incapaz independientemente de la disponibilidad de hilos. En un agente Linux, el uso de CPU es la única métrica de recurso del sistema que se aplica.
  • Verifica el uso de CPU y memoria en el host del agente en el momento del problema. Si la observabilidad nativa está habilitada, revisa los gráficos System Resource Capability, Apache Threads y Tomcat Threads en la pestaña Metrics de la página Agents de la Consola de Administración. Al revisar gráficos para un grupo de múltiples agentes, utiliza valores máximos o picos en lugar de promedios, ya que los promedios pueden ocultar un único agente sobrecargado mientras el resto del grupo parece estar en buen estado.
  • Si el grupo de agentes contiene múltiples agentes, verifica ProcessEngine.log en todos los agentes del grupo para determinar si todos los agentes fueron incapaces simultáneamente cuando la operación falló. Si solo un agente fue incapaz, la operación debería haberse enrutado a un agente capaz. Verifica que el equilibrio de carga esté configurado correctamente para el grupo.
  • Si los límites de recursos se alcanzan consistentemente, agrega agentes al grupo para distribuir la carga.
  • Si la presión de memoria es el factor desencadenante, consulta Java heap space: OutOfMemoryError.

La transformación falla: "No se pudo encontrar el archivo en el almacén de archivos local"

• Síntoma: Una operación falla durante una transformación con un error que indica que falta un archivo en el almacén de archivos local del agente:

  Failed to find file in the local file store. Will attempt a re-sync the files in the environment the next time the operation runs.
  There is no file in the local file store. File_ID = ...
  Failed to find file in the local file store. TransformID: ..., FileID: ..., Error: There is no file in the local file store. File_ID = ... [CODE:10808]
  

• Causa posible: Los metadatos de implementación de un archivo no se sincronizaron completamente desde la nube de Harmony al agente, por lo que el agente no puede localizar el archivo en tiempo de ejecución. Esto suele ser transitorio (por ejemplo, una breve interrupción de sincronización), pero también puede ocurrir después de exportar e reimportar un proyecto entre entornos.

• Resolución:
  1. Ejecuta la operación nuevamente. En la versión 11.38 del agente y posteriores, el agente se autocorrige: el error ocurre como máximo una vez por ID de archivo en un agente determinado, y el agente restaura los metadatos faltantes en la siguiente sincronización del entorno (la siguiente ejecución de operación o implementación). En la mayoría de los casos, ejecutar la operación nuevamente lo resuelve.
  2. Si el mismo archivo sigue fallando en múltiples ejecuciones en un agente actual, es probable que exista un problema más profundo, como un entorno que ha alcanzado su límite de registros de implementación o una regresión específica de la versión. Contacta con soporte de Jitterbit con el nombre de la operación que falla y los valores TransformID y File_ID del error.

Errores de instalación y actualización

Error 1720 o 1722 en la instalación de Windows

• Síntoma: La instalación del agente privado de Windows falla a mitad del proceso, con uno de estos errores del Instalador de Windows:

  Error 1722. There is a problem with this Windows Installer package. A program run as part of the setup did not finish as expected. Contact your support personnel or package vendor. ...
  

  Error 1720. There is a problem with this Windows Installer package. A script required for this install to complete could not be run.
  

  Ambos errores significan que un paso en el instalador (una acción personalizada, nombrada en el mensaje de Error 1722) no se completó. La mayoría de las veces, el paso que falla es la configuración de PostgreSQL incluida en el instalador, en cuyo caso el registro del instalador también puede mostrar un error de script KoGetDbService o KoInstallPostgreSQLNew, o [Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified, y es posible que la base de datos PostgreSQL incluida y el servicio de Windows jitterbitpostgres no se creen completamente. El mensaje puede nombrar una acción diferente, como InstallVerboseLogShipper.

• Causas posibles:

  • Una redistribución de Microsoft Visual C++ faltante o conflictiva (PostgreSQL incluido la requiere).
  • Caracteres prohibidos en la contraseña de PostgreSQL.
  • En una reinstalación, componentes de PostgreSQL restantes de un agente anterior. El desinstalador del agente no elimina PostgreSQL, el usuario de Windows jitterbitpostgres o sus entradas del registro por diseño, y estos restos pueden impedir que la nueva configuración de PostgreSQL se complete (por ejemplo, la cuenta de servicio jitterbitpostgres no se puede recrear).
  • En una reinstalación o actualización, componentes restantes del envío de registros detallado de un agente anterior. Al igual que con PostgreSQL, una desinstalación estándar no elimina el servicio de envío de registros detallado ni sus archivos, y estos restos pueden causar que la acción InstallVerboseLogShipper del instalador falle.
  • En una actualización desde una instalación avanzada anterior donde PostgreSQL estaba configurado para ejecutarse bajo una cuenta de servicio de Windows distinta de jitterbitpostgres (por ejemplo, NT AUTHORITY\NetworkService), la actualización podría fallar con Error 1720 en versiones del agente anteriores a la 12.10.

• Resolución:

  • Instala el Redistribuible de Microsoft Visual C++ de 64 bits para Visual Studio usando vc_redist.x64.exe (compatible con Visual Studio 2015, 2017 y 2019) antes de instalar el agente y mantenlo instalado, ya que eliminarlo durante una limpieza también rompe la instalación.

  • Si la contraseña de PostgreSQL contiene caracteres prohibidos, cambia la contraseña a una válida antes de reintentar la instalación.

    Nota

    En agentes privados 12.8 y posteriores, el instalador valida la contraseña de la cuenta de servicio de PostgreSQL (jitterbitpostgres) contra las restricciones de caracteres en el momento de la entrada y te solicita que la corrijas antes de que se instale PostgreSQL.

  • Si estás reinstalando después de un agente anterior, elimina completamente el PostgreSQL restante primero: sigue Desinstalar un agente privado de Windows, luego confirma que el usuario de Windows jitterbitpostgres, el programa PostgreSQL, los directorios de datos y las claves del registro de PostgreSQL se hayan eliminado.

  • Si el mensaje de Error 1722 menciona la acción InstallVerboseLogShipper, elimina el servicio de envío de registro detallado restante y sus archivos del agente anterior, luego desinstala el agente nuevamente y reinstala.

  • Si la instalación anterior es una instalación avanzada con PostgreSQL ejecutándose bajo una cuenta de servicio distinta a jitterbitpostgres, actualiza a la versión 12.10 del agente o posterior, lo que resuelve esto. En una versión anterior del agente, reconfigura el servicio PostgreSQL existente para ejecutarse bajo la cuenta de servicio de Windows jitterbitpostgres antes de actualizar.

    Si la instalación sigue fallando después de una limpieza exhaustiva, contacta al soporte de Jitterbit.

Servicio PostgreSQL eliminado después de una actualización fallida en Windows

• Síntoma: Después de una actualización fallida del agente privado en Windows, el servicio PostgreSQL (postgresql-x64-<VERSION>) ya no aparece en Servicios de Windows y los servicios del agente Jitterbit no se inician debido a una dependencia faltante.

• Causa: Esto ocurre con versiones del agente privado anteriores a 11.59 / 12.3 cuando se ingresa una contraseña incorrecta durante la actualización y el instalador no revierte correctamente. Este problema se resuelve en el agente privado 11.59 / 12.3 y posteriores, donde una contraseña incorrecta bloquea la actualización en el mismo diálogo y permite reintentar o cancelar sin afectar la instalación existente.

• Resolución:

  1. Abre un símbolo del sistema como administrador.

  2. Vuelve a registrar el servicio PostgreSQL:

     "C:\Program Files\PostgreSQL\<VERSION>\bin\pg_ctl.exe" register -N "postgresql-x64-<VERSION>" -D "C:\Program Files\PostgreSQL\<VERSION>\data"
     

     Reemplaza <VERSION> con tu número de versión de PostgreSQL. Para encontrarlo, consulta Versión de PostgreSQL incluida con el agente privado.

  3. Inicia los servicios PostgreSQL y PgBouncer:

     net start postgresql-x64-<VERSION>
     net start JitterbitPgbouncer
     

  4. Inicia todos los servicios del agente Jitterbit:

     "C:\Program Files\Jitterbit Agent\StartServices.bat"
     

  5. Una vez que el agente esté en ejecución, restablece las contraseñas del administrador de PostgreSQL y de la cuenta de servicio antes de reintentar la actualización.

Los servicios del agente no se inician después de reiniciar Windows tras una actualización

• Síntoma: Una actualización del agente privado de Windows de un agente 11.x a un agente 12.x anterior a 12.10 se completa correctamente, pero los servicios del Agente Jitterbit no se inician la próxima vez que se reinicia el sistema host.

• Posible causa: La actualización deja el servicio anterior de PostgreSQL en Windows (postgresql-x64-<VERSION>, donde <VERSION> es la versión instalada por el agente anterior) con su tipo de inicio aún configurado como Automático. Al reiniciar, este servicio más antiguo se inicia antes que el servicio PostgreSQL instalado por la actualización y ocupa el mismo puerto, lo que impide que el nuevo servicio PostgreSQL y, por lo tanto, el agente, se inicien.

• Resolución:

  • Actualizar a la versión 12.10 del agente o posterior, que elimina el servicio PostgreSQL anterior durante la actualización.
  • En una versión anterior del agente, después de actualizar, abrir Servicios de Windows, identificar el servicio postgresql-x64-<VERSION> más antiguo (el que es anterior a la actualización) y establecer su tipo de inicio en Manual o Deshabilitado, o desinstalarlo, antes de reiniciar el sistema host. Para verificar qué versión está actualmente incluida con el agente, ejecutar el comando en Same version as bundled.

La autenticación de dos factores impide la instalación del agente privado de Windows de 64 bits

• Síntoma: La instalación de un agente privado de Windows de 64 bits falla cuando la autenticación de dos factores (TFA) está habilitada en la organización.
• Resolución: Deshabilitar temporalmente la TFA, instalar el agente y luego volver a habilitar la TFA. La configuración Requerir autenticación de dos factores (TFA) se encuentra en la pestaña Gestión de usuarios de las políticas de una organización, a la que se accede desde la página Organizaciones de la Consola de administración.

Recuperar una instalación de Windows fallida

• Síntoma: La instalación o actualización de un agente privado de Windows falla o deja el agente en un estado roto.
• Resolución: Desinstalar completamente el agente y luego reinstalar el software del agente.

La instalación de Linux sin privilegios de root falla

• Síntoma: El instalador Linux Redhat Non-Root (x64) falla.

• Resolución: Verificar lo siguiente:

  • El usuario sin privilegios de root tiene privilegios de sudo. Un administrador del sistema debe agregar el usuario al grupo wheel. Para verificar la pertenencia actual al grupo, ejecutar groups.

  • Cuando se inicia sesión como usuario jitterbit, la variable de entorno JITTERBIT_HOME está configurada en la ubicación de instalación:

    echo $JITTERBIT_HOME
    

    El resultado debe ser /opt/jitterbit. Esto se establece mediante $HOME/.bashrc.d/jitterbit cuando se siguen las instrucciones de instalación. Para configurarlo manualmente, ejecutar:

    . /opt/jitterbit/scripts/set.env
    

  • Si el instalador falla con un error OPENSSL_3.4.0, se trata de un problema conocido en RHEL 9.7 y posterior. Consultar RHEL 9.7 y posterior: la instalación del agente privado sin privilegios de root muestra un error de OpenSSL en los problemas conocidos del agente privado para obtener una solución alternativa.

Controlador JDBC: "No se encontró un controlador adecuado"

• Síntoma: Una conexión de base de datos falla porque el controlador JDBC requerido no está instalado en el agente, con un error como No suitable driver found for jdbc:<subprotocol>://....
• Causa: Jitterbit no incluye todos los controladores JDBC. El controlador requerido debe instalarse manualmente.
• Resolución: Instalar el controlador requerido manualmente: registrarlo en JdbcDrivers.conf y copiar el archivo .jar del controlador a JITTERBIT_HOME/tomcat/drivers/lib/, luego reiniciar el agente. Para ver los pasos completos, consultar Instalar un controlador JDBC.

Conector no descargado en el agente

• Síntoma: Las operaciones fallan con errores que indican que un conector no está disponible o no se encuentra en el agente, típicamente después de que se lanza una nueva versión del conector o después de implementar un proyecto que utiliza un conector que el agente aún no ha descargado:

  This connector was not found on the Jitterbit Agent. Please be patient with us while the connector is downloaded across the agents. This may take up to several minutes
  

• Posibles causas:

  • La versión del conector requerida por el proyecto aún no se ha descargado de la nube al agente. Esto suele ser transitorio y se resuelve en unos minutos.
  • Para agentes privados: el agente no puede alcanzar la nube de Harmony para descargar el conector.

• Resolución:

  • En Studio, abre la conexión afectada y haz clic en Test. Esto activa la descarga de la versión más reciente del conector desde la nube en el agente.
  • Si el conector aún no se descarga, verifica si la política de organización Disable Auto Connector Update está habilitada. Cuando lo está, el botón Test no descarga versiones de conectores. Consulta Agent Management.
  • Para descargar el conector sin cambiar la política, ve a la página Agents de la Consola de Administración, selecciona el grupo de agentes y elige Action > Update connectors. Esto fuerza una actualización del conector en todo el grupo y no se ve afectado por la política Disable Auto Connector Update.
  • Para agentes privados, verifica que el host del agente pueda alcanzar la nube de Harmony. Consulta Agent offline or unreachable.

La instalación del agente no puede registrarse a través de un proxy corporativo

• Síntoma: Una instalación de agente privado en un host detrás de un proxy corporativo falla durante el paso de registro inicial, y el instalador reporta que no pudo alcanzar la nube de Harmony:

  Could not connect to Jitterbit Harmony cloud
  

• Posibles causas:

  • El proxy está bloqueando la conexión del agente a la nube de Harmony durante el registro.
  • El proxy requiere autenticación que la configuración del proxy del agente no proporciona. Los agentes privados admiten autenticación de proxy, incluyendo un dominio NTLM. Consulta Proxy server for Jitterbit private agents.

• Resolución:

  1. Configura el proxy durante la configuración del agente para que el instalador pueda alcanzar la nube de Harmony a través de él, proporcionando las credenciales del proxy (y el dominio NTLM, si el proxy lo requiere). Consulta Configure a proxy during agent setup.
  2. Si el registro aún falla a través del proxy, pide a tu equipo de red que permita los dominios e direcciones IP de Jitterbit a través del proxy, o que los omita. Las URL de Harmony específicas de la región se documentan en Allowlist information.
  3. Vuelve a ejecutar el instalador una vez que el proxy esté configurado o el host pueda alcanzar la nube de Harmony.

Problemas de rendimiento y recursos

Espacio de heap de Java: OutOfMemoryError

• Síntoma: Las operaciones que procesan archivos grandes o ejecutan muchas operaciones simultáneamente fallan con:

  java.lang.OutOfMemoryError: Java heap space
  

• Causa: El tamaño máximo de heap de Java (-Xmx) del agente privado es demasiado pequeño para la carga de trabajo (archivos grandes o alta concurrencia de trabajos).

• Resolución:
  1. Aumentar el heap máximo de Java del agente privado. Consulta Memoria de heap de Tomcat para saber cómo cambiar el valor -Xmx (por ejemplo, de -Xmx1024m a -Xmx4096m).
  2. Reinicia los servicios del agente después de realizar el cambio.
  3. Para operaciones que procesan archivos grandes, configura fragmentación para reducir el uso de memoria por trabajo. Studio aplica transformaciones de streaming automáticamente cuando califican.
  4. Si la observabilidad nativa está habilitada, utiliza el gráfico System Resource Capability en la pestaña Métricas de la página Agentes de la Consola de Administración para monitorear el uso de memoria a lo largo del tiempo y ajustar el heap según la carga de trabajo.

Espacio en disco y acumulación de registros

• Síntoma: El host del agente privado se queda sin espacio en disco, lo que puede causar que PostgreSQL se apague u operaciones fallen con errores de permisos. Los archivos de registro y temporales se acumulan en los directorios del agente, especialmente en agentes que procesan altos volúmenes.
• Resolución:
  • Verifica el espacio en disco disponible en el host del agente.
  • Identifica archivos grandes. Los registros del agente y archivos temporales se encuentran en JITTERBIT_HOME/log, JITTERBIT_HOME/tomcat/logs (catalina.out) y JITTERBIT_HOME/DataInterchange/Temp. Consulta Archivos de registro para la lista completa. Un archivo de registro individual puede crecer a varios gigabytes cuando un componente registra excesivamente (por ejemplo, un conector detallado inundando catalina.out) o cuando un error se repite (por ejemplo, una conexión de base de datos fallida repitiéndose en ProcessEngine.log). Borra archivos de tamaño excesivo si el espacio es crítico; borrar el archivo y reiniciar el agente también puede detener el error subyacente.
  • Confirma que el servicio de limpieza se está ejecutando y se respeta su retención. En la sección [FileCleanup] de jitterbit.conf, verifica que AutoStart sea true y revisa FrequencyInHours. La retención por directorio se establece en CleanupRules.xml usando NumDays o NumOfHours.
  • Si el servicio de limpieza no puede eliminar archivos de registro activos (Tomcat mantiene sus registros de stdout y stderr abiertos en Windows), aumenta FileAge para ese directorio en CleanupRules.xml a al menos un día para que la limpieza no afecte archivos que aún se están escribiendo.
  • Si archivos .dmp de volcado de fallos grandes están consumiendo el disco, consulta Los archivos de mini-dump de JVM llenan el disco del agente.

Bucle de reinicio del servicio del agente

• Síntoma: Los servicios del agente se bloquean y reinician repetidamente. Tomcat o el Process Engine se detiene e inicia en un bucle sin mantenerse en línea, y las operaciones fallan con errores como Tomcat service is not running. Si jitterbit status muestra todos los servicios saludables en el host pero el estado mostrado solo parpadea entre Running, Unknown y Stopped, se trata de un problema de conectividad en lugar de un bucle de bloqueo. Consulta Agente sin conexión o inaccesible.

• Posibles causas:

  • Un proceso Jitterbit huérfano de una ejecución anterior (un proceso de Tomcat, Process Engine o scheduler) aún está ocupando el puerto del servicio, por lo que cada reinicio falla con java.net.BindException: Address already in use y el agente se cicla.
  • El host se queda sin memoria y el sistema operativo termina el proceso. Esto puede ocurrir cuando el host tiene muy poca memoria para la carga de trabajo, o cuando el límite de memoria de un contenedor se establece demasiado bajo.
  • El host del agente tiene poco espacio en disco, o la base de datos PostgreSQL interna ha crecido lo suficiente como para fallar al iniciarse.
  • El Process Engine se bloquea repetidamente bajo carga sostenida.

• Resolución:

  • Confirma que se trata de un verdadero bucle de bloqueo. Revisa los registros de Tomcat en JITTERBIT_HOME/tomcat/logs/ y ProcessEngine.log para ver la excepción registrada en cada reinicio. Un java.net.BindException: Address already in use indica que un proceso huérfano está ocupando el puerto.
  • Detén el agente y finaliza cualquier proceso Jitterbit restante antes de reiniciarlo. Con el agente detenido, busca procesos extraviados: en Linux, ejecuta ps aux | grep -E 'tomcat|jitterbit' y usa kill en cualquier ID de proceso restante; en Windows, finaliza cualquier proceso Jitterbit o Tomcat extraviado en el Administrador de tareas. Inicia el agente nuevamente una vez que no quede ninguno.
  • Verifica eventos de falta de memoria. En Windows, revisa los registros de Aplicación y Sistema en el Visor de eventos; en Linux, ejecuta journalctl -u jitterbit o revisa /var/log/syslog para eventos del asesino de OOM. Si el host se está quedando sin memoria, aumenta la memoria disponible (o el límite de memoria del contenedor). Consulta Espacio de montón Java: OutOfMemoryError.
  • Verifica el espacio en disco y la base de datos interna. Un disco lleno o una base de datos PostgreSQL inflada pueden bloquear los servicios en cada reinicio. Consulta Espacio en disco y acumulación de registros.
  • Si los registros muestran que el Motor de procesos se bloquea en una operación específica, contacta al soporte de Jitterbit con los detalles de la operación y los registros del agente.
  • Si la observabilidad nativa está habilitada, abre la pestaña Métricas de la página Agentes de la Consola de administración y revisa los gráficos de servicios de Tomcat y Motor de procesos para identificar cuándo comenzaron a fallar los servicios.

Las operaciones se agotaron o ignoraron la configuración de tiempo de espera

• Síntoma: Las operaciones se ejecutan indefinidamente o más tiempo del esperado. Para operaciones activadas por API, la configuración de tiempo de espera configurada en Studio parece no tener efecto, y las operaciones pueden permanecer atrapadas en estado En ejecución.

• Posibles causas:

  • De forma predeterminada, las operaciones activadas por API Manager ignoran la configuración de tiempo de espera de operación de Studio. La configuración EnableAPITimeout en jitterbit.conf debe habilitarse explícitamente para que las operaciones de API respeten los valores de tiempo de espera.
  • No se establece un tiempo de ejecución máximo de operación, por lo que las operaciones se ejecutan sin un límite de tiempo fijo.

• Resolución:

  1. Para aplicar la configuración de tiempo de espera de operación para operaciones activadas por API, establece EnableAPITimeout=true en la sección [Settings] de jitterbit.conf.
  2. Para limitar el tiempo de ejecución total de cualquier operación, establece MaxOperationRuntimeSeconds en la sección [ProcessEngine] de jitterbit.conf. Esto requiere que RunOperationsInSeparateProcess sea true (el valor predeterminado).
  3. Reinicia los servicios del agente después de realizar cambios en jitterbit.conf.

El rendimiento del agente no cambió después de aumentar max.concurrent.requests

• Síntoma: Después de aumentar max.concurrent.requests en jitterbit-agent-config.properties, el rendimiento del agente no mejora.

• Posibles causas:

  • Solo se cambió max.concurrent.requests. El rendimiento del agente también depende de los grupos de subprocesos de Tomcat y Apache y de los grupos de conexiones HTTP, por lo que aumentar solo esta configuración sin escalar las otras en conjunto no produce ganancia.
  • El host del agente no tiene suficiente CPU o memoria para la concurrencia agregada, o el agente está entrando en un estado incapaz bajo carga.

• Resolución:

  • Sigue el procedimiento de ajuste completo en lugar de cambiar solo max.concurrent.requests, escalando la configuración del grupo de subprocesos y del grupo de conexiones relacionados en conjunto. Consulta Rendimiento y ajuste del agente.
  • Confirma que el host del agente tiene suficiente margen de CPU y memoria para la concurrencia más alta. Si el agente se bloquea o entra en un estado incapaz bajo carga, consulta Bucle de reinicio del servicio del agente y Espacio de montón Java: OutOfMemoryError.

Ralentización de transformación XML después de actualizar a agente 11.45 o posterior

• Síntoma: Después de actualizar un agente privado a la versión 11.45 o posterior, una transformación que itera sobre un arreglo grande tarda más en ejecutarse que en la versión 11.44. La ralentización es específica de rutas de mapeo que utilizan la notación # para iterar sobre cada elemento de un arreglo grande (aproximadamente varios cientos a algunos miles de registros). Las transformaciones que no iteran sobre arreglos grandes no se ven afectadas.
• Causa posible: La biblioteca de análisis XML utilizada por el agente se actualizó en la versión 11.45, y la versión actualizada analiza datos XML grandes más lentamente. Esto afecta las transformaciones que iteran sobre un arreglo grande, porque el mapeo atraviesa repetidamente los datos analizados.
• Resolución:
  • Revisar las rutas de mapeo de la transformación para la notación #. Si una ruta utiliza # para iterar sobre un arreglo pero solo se necesita el primer elemento, eliminar # y volver a implementar. Eliminar # mapea solo el primer elemento, así que aplicar esto solo donde no sea necesario iterar sobre el arreglo completo.
  • Si el mapeo debe iterar sobre el arreglo completo, procesar menos registros por ejecución dividiendo un conjunto de datos grande en lotes más pequeños, de modo que cada transformación atraviese un arreglo más pequeño.

Archivos de mini-volcado JVM llenan el disco del agente

• Síntoma: El agente genera continuamente archivos grandes de bloqueo JVM (mini-volcados .dmp y .mdmp, y archivos hs_err_pid*.log) en <JITTERBIT_HOME>/Tomcat/temp (o, en compilaciones más antiguas, la carpeta Tomcat directamente), consumiendo el espacio en disco del host del agente. Esto afecta a agentes privados de Windows en versiones anteriores a 11.49.

• Causas posibles:

  • El recopilador de estadísticas de disco AgentStats del agente bloquea la JVM mientras recopila métricas de disco. Esto afecta a agentes en versiones anteriores a 11.49.
  • En agentes que ejecutan 11.47 o 11.48, un bloqueo separado en el Motor de Procesos puede producir los mismos archivos de bloqueo.

• Resolución: Actualizar el agente privado a la versión 11.49 o posterior, que resuelve ambas causas.

  Si no es posible una actualización inmediata y los archivos de bloqueo provienen de la recopilación de estadísticas de disco, se puede desactivar esa recopilación como solución temporal (la marca DiskStatsEnabled está disponible en el agente 11.44.1 y posterior):

  1. En jitterbit.conf, agregar:

     [AgentStats]
     DiskStatsEnabled=false
     

  2. Reiniciar los servicios del agente. Los archivos de bloqueo existentes se pueden eliminar de forma segura para recuperar espacio en disco.

  3. Si se está en 11.47 o 11.48 y los archivos de bloqueo continúan, actualizar a 11.49 o contactar al soporte de Jitterbit para obtener una solución temporal.

Problemas de base de datos

Fallos de conexión TranDb

• Síntoma: Las operaciones fallan con errores que hacen referencia a la base de datos PostgreSQL interna del agente privado, o los servicios internos del agente no se inician porque se ha alcanzado su límite de conexión. Los fallos repetidos también pueden inundar ProcessEngine.log, haciéndola crecer a varios GB:

  Failed to connect to back-end database 'TranDb'
  

  FATAL: query_wait_timeout
  

  FATAL: remaining connection slots are reserved for non-replication superuser connections
  

• Causas posibles:

  • El límite max_connections de PostgreSQL interno, o el límite max_db_connections de PgBouncer, es demasiado bajo para la carga de trabajo del agente.
  • Las operaciones se están acumulando bajo carga pesada o una ralentización de red o punto final, manteniendo conexiones de base de datos hasta que se agota el grupo de PgBouncer (query_wait_timeout).
  • En un agente de Windows, IP Helper está interfiriendo con las conexiones de base de datos locales del agente.

• Resolución:

  • Las versiones recientes del agente incluyen límites de conexión más altos para PostgreSQL y PgBouncer de forma predeterminada, así que primero confirma que el agente esté en una versión actual. Si un agente actual sigue agotando su límite de conexión, contacta con soporte de Jitterbit para aumentarlo bajo orientación de soporte. Las instancias agrupadas de PostgreSQL y PgBouncer deben modificarse solo bajo orientación de soporte.
  • Si los límites ya son adecuados, investiga qué está manteniendo las conexiones abiertas: revisa la carga del host del agente y cualquier lentitud de red o punto final ascendente que esté ralentizando las operaciones.
  • En un agente Windows, desactiva IP Helper. Consulta Problema de IPv6 en Windows.

PostgreSQL agrupado en Linux usa MD5 en lugar de SCRAM-SHA-256

• Síntoma: Deseas cambiar el método de autenticación de PostgreSQL agrupado en un agente privado de Linux de MD5 a SCRAM-SHA-256, pero el agente continúa usando MD5.

• Posibles causas:

  • MD5 es el cifrado de contraseña predeterminado para PostgreSQL agrupado en agentes privados de Linux. SCRAM-SHA-256 fue el predeterminado solo en las versiones 12.6 y 12.7; la versión 12.8 revirtió el predeterminado a MD5. Cuando actualizas un agente de Linux desde 12.6 o 12.7, el instalador te solicita que restablezca el cifrado a MD5 o mantengas SCRAM-SHA-256; consulta Actualizar un agente de Linux.
  • Editar solo pg_hba.conf y postgresql.conf no completa el cambio. PgBouncer también debe reconfigurarse con el hash del verificador SCRAM, o el agente no se inicia.

• Resolución: Para cambiar un agente privado de Linux a SCRAM-SHA-256, sigue la guía SCRAM en PostgreSQL. SCRAM-SHA-256 es un método de autenticación más seguro, mientras que MD5 es más eficiente, por lo que el cambio es una modificación deliberada y de varios pasos: la guía reconfigura PostgreSQL agrupado, actualiza las contraseñas de usuario y reconfigura PgBouncer con el nuevo hash. Reconfigurar la instancia agrupada es la forma compatible para habilitar SCRAM. No reemplaces la instancia agrupada con tu propio servidor PostgreSQL para obtener SCRAM: los agentes que usan una instancia de PostgreSQL distinta a la agrupada no son compatibles.

PostgreSQL: Apagado rápido administrativo

• Síntoma: Todas las operaciones fallan porque la base de datos del agente no está disponible (las operaciones pueden estancarse en estado Pendiente), y el registro de PostgreSQL registra un apagado rápido:

  received fast shutdown request
  

  Las operaciones de conexión también pueden reportar FATAL: terminating connection due to administrator command.

• Posibles causas:

  • Una acción externa o del sistema detuvo o reinició PostgreSQL: un reinicio del SO, una actualización de Windows o tarea programada, o una herramienta de monitoreo o copia de seguridad que reinicia servicios.
  • El host del agente se quedó sin CPU o memoria, causando que Tomcat se bloqueara y llevara PostgreSQL con él.

• Resolución:

  • Reinicia los servicios de PostgreSQL y del agente Jitterbit (o reinicia el host del agente) para recuperarte. Si las operaciones permanecen estancadas en estado Pendiente o En ejecución después de que PostgreSQL esté de vuelta, contacta con soporte de Jitterbit, ya que el grupo de conexiones de la base de datos del agente puede no haberse recuperado.
  • Identifica qué detuvo PostgreSQL: revisa el registro de eventos del SO (en Windows, Visor de eventos) alrededor del momento del fallo para reinicios, actualizaciones, tareas programadas, bloqueos de servicios, o herramientas de copia de seguridad y monitoreo que reinician servicios. Prevén o reprograma lo que lo está deteniendo, y establece que el servicio de PostgreSQL se reinicie automáticamente en caso de fallo.
  • Verifica la CPU y memoria del host del agente. Si los servicios de Jitterbit se están bloqueando bajo carga, consulta Bucle de reinicio del servicio del agente y Espacio de pila de Java: OutOfMemoryError.

Red e conectividad

Fallo en el protocolo de enlace de certificados (TLS)

• Síntoma: Las operaciones que se conectan a puntos finales seguros fallan durante el protocolo de enlace TLS, con errores como:

  error:0A000152:SSL routines::unsafe legacy renegotiation disabled
  

  SSLHandshakeException: Received fatal alert: protocol_version
  

  PKIX path building failed: unable to find valid certification path to requested target
  

• Posibles causas:

  • El punto final utiliza renegociación heredada de TLS, que el agente bloquea de forma predeterminada.
  • El agente y el punto final no pueden negociar una versión o cifrado TLS común. Los agentes de la versión 11.x y 12.x incluyen diferentes bibliotecas de seguridad, por lo que un punto final que no se conecta en un agente 11.x puede conectarse en un agente 12.x.
  • El certificado del punto final (o uno de sus intermediarios) no es de confianza para el agente porque su CA emisora no está en el almacén de confianza cacerts del JRE del agente.

• Resolución: Desde el host del agente, ejecuta lo siguiente para confirmar qué versión de TLS negocia el punto final y si el protocolo de enlace se realiza correctamente a nivel de red:

  openssl s_client -connect hostname:port
  

  Luego aplica la solución que coincida con el error:

  • Si el error es unsafe legacy renegotiation disabled, establece AllowUnsafeLegacyRenegotiation=true en la sección [Settings] de jitterbit.conf y reinicia el agente. Esta configuración requiere la versión 11.39 del agente o posterior.
  • Si el error es PKIX path building failed: unable to find valid certification path to requested target, el certificado del punto final (o uno de sus intermediarios) no está en el almacén de confianza cacerts del JRE del agente. Utiliza keytool -import en el cacerts del JRE del agente (contraseña predeterminada changeit) para importar los certificados faltantes y luego reinicia los servicios del agente. Para una base de datos SQL Server a la que se accede a través de una conexión de Base de datos, también puedes resolver esto en la configuración del controlador de la conexión en lugar del almacén de confianza, tanto en agentes en la nube como privados. Consulta SQL Server: La conexión falla con un error de ruta de certificado PKIX.
  • Si persiste un fallo de negociación o protocolo de enlace TLS, especialmente en un agente 11.x, actualiza a un agente 12.x actual, que incluye bibliotecas de seguridad actualizadas y un almacén de confianza de certificados actualizado.

La conexión de zona de pruebas de Salesforce falla con discrepancia de certificado

• Síntoma: Una conexión de agente privado a un punto final que requiere Indicación de Nombre de Servidor (SNI) falla con una discrepancia de certificado, mientras que la misma conexión se realiza correctamente desde un grupo de agentes en la nube o desde una prueba directa de openssl o curl en el host del agente. El caso más común es una URL de zona de pruebas de Salesforce que termina en .sandbox.my.salesforce.com:

  Certificate for <your-domain.sandbox.my.salesforce.com> doesn't match any of the subject alternative names: ...
  

  Otros puntos finales afectados incluyen hosts que comparten una única IP detrás de alojamiento virtual.

• Causa: El protocolo de enlace TLS no incluye la extensión SNI, por lo que el servidor devuelve un certificado predeterminado en lugar del solicitado para el host. Para una zona de pruebas de Salesforce, el equilibrador de carga devuelve el certificado de producción, cuyos nombres no cubren *.sandbox.my.salesforce.com. SNI se envía de forma predeterminada, por lo que cuando falta, algo lo está suprimiendo o eliminando.

• Resolución:

  1. Confirma que SNI es la causa. Desde el host del agente, compara el certificado devuelto con y sin SNI:

     openssl s_client -connect HOST:443 -servername HOST   # certificate when SNI is sent
     openssl s_client -connect HOST:443                    # certificate when SNI is omitted
     

Si el primero devuelve el certificado correcto y el segundo devuelve el que no coincide, SNI es la causa.

1. Verifica si SNI está explícitamente deshabilitado en las opciones de Java del agente y elimínalo si es así. En Windows, abre el Editor del Registro en HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Apache Software Foundation\Procrun 2.0\Jitterbit Tomcat Server\Parameters\Java y edita el valor Options; en Linux, verifica JAVA_OPTS en /etc/sysconfig/jitterbit. Elimina -Djsse.enableSNIExtension=false si está presente (esta configuración suprime SNI). Reinicia los servicios del agente.
2. Si SNI sigue faltando después de eso, un dispositivo de red, proxy o pila de red de VM entre el agente y el endpoint lo está eliminando. Tu equipo de red debe permitir que la extensión SNI pase.

Si la conexión también falla desde un grupo de agentes en la nube, SNI no es la causa. Es posible que el certificado del servidor no incluya el host en sus Nombres Alternativos del Asunto. Para Salesforce, agrega la URL de MyDomain del sandbox al certificado de Salesforce, o consulta Certificado con Nombre Alternativo del Asunto (SAN) no coincidente.

FTP: Tiempo de espera agotado en la conexión de datos

• Síntoma: El inicio de sesión FTP es exitoso pero la lista de archivos o la transferencia de archivos se cuelga y agota el tiempo de espera.

• Posibles causas:

  • El modo de conexión FTP (activo vs. pasivo) es incompatible con la configuración de red o firewall.
  • El rango de puertos pasivos definido en el servidor FTP no está abierto en el firewall corporativo.

• Resolución:

  • En la configuración de conexión de FTP, activa o desactiva la casilla Modo Pasivo. El modo pasivo generalmente se prefiere para agentes detrás de un firewall.
  • Confirma con tu equipo de red que el rango de puertos pasivos configurado en el servidor FTP está abierto en el firewall entre el agente y el servidor FTP.
  • Para capturar registros detallados a nivel de conexión, habilita el registro de depuración de curl configurando CurlDebugDir en la sección [Settings] de jitterbit.conf. Consulta Registros de Curl.

SSH: La conexión SFTP falla debido a una ruta de archivo de clave incorrecta

• Síntoma: Las operaciones SFTP fallan en un agente Windows aunque los archivos de clave SSH estén correctamente instalados.
• Causa: Los valores de ruta PrivateKeyFile y PublicKeyFile en la sección [SSH] de jitterbit.conf utilizan separadores de barra invertida de Windows (\), que no son compatibles.
• Resolución: Utiliza barras diagonales en todas las rutas de archivos de clave SSH en jitterbit.conf, incluso en Windows (por ejemplo, C:/jitterbit/keys/id_rsa). Consulta [SSH].

Configuración de SFTP SSH faltante o en la sección jitterbit.conf incorrecta

• Síntoma: Las operaciones SFTP que utilizan una clave privada para la autenticación fallan con un error de archivo de clave privada vacío después de una actualización o reinicio del agente. La configuración de clave SSH agregada al jitterbit.conf local también puede dejar de surtir efecto después de que el agente se reinicia.

  CURL_DEBUG_TEXT: Using SSH private key file ''
  CURL_DEBUG_TEXT: SSH public key authentication failed: Unable to extract public key from private key file
  

• Posibles causas:

  • La configuración remota del agente está habilitada (está habilitada de forma predeterminada), por lo que la configuración administrada a través de la pestaña Configuración de Jitterbit de la Consola de Administración tiene prioridad. La configuración de clave SSH agregada solo al jitterbit.conf local puede no surtir efecto o no retenerse después de que el agente se reinicia.
  • La configuración de clave SSH (PrivateKeyFile, PrivateKeyPassphrase, PublicKeyFile) está en la sección incorrecta. Las versiones más nuevas del agente analizan estrictamente e ignoran la configuración de SSH colocada fuera de la sección [SSH] (por ejemplo, bajo [SSL]).

• Resolución:

  1. Si la configuración remota está habilitada, agrega la configuración de clave SSH ahí: abre el cajón de detalles del grupo de agentes para el grupo de agentes, selecciona la pestaña Jitterbit Configuration y agrégalos bajo la sección SSH. Consulta Jitterbit configuration.
  2. Si el archivo local jitterbit.conf es la fuente de configuración, confirma que la configuración de clave SSH se encuentre bajo [SSH] (no [SSL]).
  3. Reinicia los servicios del agente.
  4. Para solucionar problemas adicionales de autenticación de clave SFTP (campos de contraseña, frase de contraseña, formato de clave), consulta SFTP "Login denied. Authentication failure." cuando se usan claves SSH.

Error de autenticación SFTP en un servidor específico (desajuste de cifrado cURL)

• Síntoma: Una conexión SFTP que usa autenticación de clave SSH falla en un agente privado con Login denied. Authentication failure., pero otras conexiones SFTP desde el mismo agente (usando la misma clave) funcionan correctamente, y conectarse al servidor que falla desde la línea de comandos del SO también funciona.

  Failed to get ftp directory list for url sftp://... Login denied. Authentication failure.
  

• Causa: El servidor SFTP requiere cifrados SSH más nuevos, intercambio de claves o algoritmos de clave de host que la biblioteca cURL incluida en versiones anteriores del agente no admite. Los servidores que aún aceptan los algoritmos más antiguos continúan funcionando, por lo que la misma clave funciona contra otros hosts y desde la línea de comandos del SO.

• Resolución: Actualiza el agente privado a la versión 11.37 o posterior, que incluye una biblioteca cURL actualizada con soporte para cifrados SSH actuales, intercambio de claves y algoritmos de clave de host.

Proxy HTTPS: La autenticación básica a través del túnel proxy falla

• Síntoma: Cuando el agente se conecta a través de un proxy HTTPS que requiere autenticación básica, las conexiones a través del túnel proxy fallan con un error de autenticación.
• Causa: Las versiones modernas de JDK deshabilitan la autenticación básica durante la tunelización de proxy HTTPS de forma predeterminada. La propiedad de JVM jdk.http.auth.tunneling.disabledSchemes bloquea la autenticación básica a menos que se borre explícitamente.
• Resolución: Agrega -Djdk.http.auth.tunneling.disabledSchemes="" a CATALINA_OPTS antes de iniciar Tomcat. Para obtener instrucciones paso a paso para Windows, Linux y Docker, consulta Allow basic authentication during HTTPS proxy tunneling.

Agentes privados en redes restringidas: Conectividad solo de salida

• Síntoma: Al implementar agentes privados detrás de un firewall corporativo estricto o en un entorno restringido (por ejemplo, OpenShift) junto con una puerta de enlace de API privada, los equipos de red a veces preguntan qué puertos de entrada deben abrirse en el agente para que Harmony o la puerta de enlace lo alcancen.

• Causa: Los agentes privados no requieren que se abra ningún puerto de entrada, debido a cómo funciona la conectividad del agente:

  • Los agentes privados no aceptan conexiones de entrada desde Harmony ni desde una puerta de enlace de API privada. El agente establece una conexión WebSocket de salida a Harmony sobre HTTPS (puerto 443). Todo el tráfico desde Harmony y desde la puerta de enlace al agente se enruta de vuelta a través de esta conexión preestablecida.
  • Una puerta de enlace de API privada envía solicitudes de API a Harmony, y Harmony enruta la solicitud al agente apropiado a través del WebSocket de salida existente. El agente enruta la carga útil de respuesta de API de vuelta a la puerta de enlace de API privada, por lo que el agente también debe poder alcanzar la puerta de enlace (directamente o a través de su equilibrador de carga en una implementación de múltiples puertas de enlace).

• Resolución:

  • Abrir HTTPS saliente (puerto 443) desde el host del agente hacia las URLs de la región de Harmony. La conexión se actualiza a WSS (WebSocket seguro) para la comunicación bidireccional continua. No es necesario abrir puertos entrantes en el host del agente para Harmony ni para la puerta de enlace.
  • Al configurar el firewall, incluir en la lista de permitidos los servicios de Jitterbit específicos de la región que se enumeran en Comunicación saliente, la sección que aplica a un agente privado detrás de un firewall.
  • Si el agente se ha configurado para usar puertos no predeterminados (personalizados), permitir también esos puertos a través del firewall corporativo. Consultar Puertos de red.
  • Si se implementa una puerta de enlace de API privada, también permitir la conectividad saliente desde cada host del agente hacia la puerta de enlace (directamente o a través de su balanceador de carga en una implementación de múltiples puertas de enlace). El agente se conecta a la puerta de enlace para devolver la carga útil de respuesta de la API. Para ver el flujo de solicitud completo, consultar Arquitectura del sistema de puerta de enlace de API privada.

La API personalizada devuelve 504 pero el registro de operaciones muestra éxito

• Síntoma: Una API personalizada devuelve un tiempo de espera de puerta de enlace 504, pero el registro de operaciones en la página Runtime de la Consola de Administración muestra que la operación se completó correctamente.
• Causa: Cuando una carga útil de solicitud o respuesta (encabezados más cuerpo, comprimida) supera aproximadamente 1 KB, la puerta de enlace de API en la nube de Jitterbit almacena la carga útil en etapas, y el agente privado realiza una conexión saliente al host jitterbitsysservice de su región para descargar la carga útil de solicitud (o cargar la carga útil de respuesta) antes de completar la operación. Si el host del agente no puede alcanzar ese host, la transferencia agota el tiempo de espera y la API devuelve un 504 aunque la operación en sí se haya ejecutado. La verificación de conexión del agente estándar no verifica la conectividad al host jitterbitsysservice, por lo que el agente puede parecer completamente conectado mientras este host permanece bloqueado.
• Resolución:
  1. Agregar el host jitterbitsysservice de su región (por ejemplo, jitterbitsysservice.jitterbit.net) y sus direcciones IP estáticas a la lista de permitidos saliente en el firewall del host del agente privado. Consultar Información de lista de permitidos de Jitterbit para las URLs e IPs específicas de la región.
  2. Verificar la conectividad ejecutando una prueba HTTP desde el host del agente hacia la URL jitterbitsysservice de su región, luego confirmar que la API ya no agota el tiempo de espera.

Problema de IPv6 en Windows

• Síntoma: Algunos agentes experimentan problemas de conectividad cuando IPv6 está habilitado en el host de Windows. Esto puede manifestarse, por ejemplo, como operaciones atascadas en estado Pendiente con un ProcessEngine.log en rápido crecimiento, cuando el servicio IP Helper se bloquea y el agente pierde su conexión a la base de datos interna.

• Resolución: Deshabilitar tanto IPv6 como IP Helper en el host de Windows.

  Deshabilitar IPv6 de la siguiente manera:

  1. Abrir Panel de control > Red e Internet > Conexiones de red.
  2. Abrir las Propiedades de la conexión de red.

  3. Desmarcar la casilla de Protocolo de Internet versión 6 (TCP/IPv6):

     

  Deshabilitar IP Helper de la siguiente manera:

  1. Abrir Servicios.
  2. Localizar IP Helper, hacer clic derecho y seleccionar Propiedades.
  3. Hacer clic en Detener, luego establecer Tipo de inicio en Deshabilitado:

Azure VM: Conexiones perdidas y errores de WebSocket/I/O

Esta sección cubre la solución de problemas para agentes privados instalados en máquinas virtuales (VM) de Microsoft Azure. Para ajustes generales de rendimiento, consulta Ajuste de rendimiento del agente privado.

Conexiones perdidas

Azure establece el tiempo de espera inactivo de WebSocket en 4 minutos, mientras que el intervalo de latido predeterminado del agente privado es de 5 minutos. Para resolver las conexiones perdidas, reduce el intervalo de latido:

1. Abre jitterbit-agent-config.properties en un editor de texto:

   • Linux: <JITTERBIT_HOME>/Resources/
   • Windows: C:\Program Files\Jitterbit Agent\Resources

2. Busca la configuración agent.heart.beat.interval:

   #Agent heart beat interval (IN MINUTES)
   agent.heart.beat.interval=5
   

3. Cambia el valor a agent.heart.beat.interval=3.

4. Guarda el archivo y reinicia el agente.

Errores de WebSocket e I/O

Se pueden resolver los errores de WebSocket e I/O actualizando el tiempo de espera inactivo de IP de la VM de Azure, el tiempo de espera inactivo de TCP de la puerta de enlace NAT y el tiempo de espera de flujo de la red virtual (VNET) a 15 minutos cada uno. Esto se cubre en los siguientes pasos.

Identificar errores relevantes

Revisa los registros de operación y jitterbit-agent.log para los siguientes mensajes.

Errores del registro de operación:

The operation "Example Operation" completed successfully.

No message found while removing message in cache for: Message Info: AgentId: 000001 AgentGroupId: 000001 MessageId: XXX Message Version (Agent): XXXX Message Version (Harmony): XXX Counter (Harmony): 1 Submitted Timestamp (Harmony):2024-01-20 11:55:00.700 , message will be retried later OperationInstanceGUID: XXX

Run message could not reach the agent.

Errores del registro del agente:

2024-01-20 12:00:00 request handler thread #10642  INFO org.jitterbit.integration.server.api.util.AgentRetryExecutor:53 - Agent Message Receipt (OperationInstanceGUID: XXX) failed. Retrying....
2024-01-20 12:00:00 request handler thread #10642 ERROR org.jitterbit.integration.server.api.util.AgentRetryExecutor:55 - org.springframework.web.client.ResourceAccessException: I/O error on PUT request for "https://na-east.jitterbit.com/jitterbit-cloud-restful-service/agent/ackmsgreceipt": Read timed out; nested exception is java.net.SocketTimeoutException: Read timed out

E:2024-01-20 12:00:00 request handler thread #884 ERROR org.jitterbit.integration.server.messaging.agent.listener.AgentMessageListener:231 - No message found while removing message in cache for: Message Info: AgentId: 000001 AgentGroupId: 000001 MessageId: XXX Message Version (Agent): XXXX Message Version (Harmony): XXX Counter (Harmony): 1 Submitted Timestamp (Harmony):2024-01-20 11:55:00.700 , message will be retried later OperationInstanceGUID: XXX

Detener el agente con drenaje

Detén con drenaje el agente antes de actualizar cualquier configuración de tiempo de espera. Si hay más de un agente en el grupo afectado, detén con drenaje todos ellos.

Aislar recursos del agente

Se recomienda que la VM del agente y sus recursos asociados (VNET, IP, puerta de enlace NAT, NIC y NSG) se separen en su propio grupo de recursos en Azure.

Actualizar el tiempo de espera inactivo de la IP

1. En el portal de Azure, navega al grupo de recursos asociado con la VM del agente.

2. Haz clic en el elemento de IP asociado con la VM:

   

3. Haz clic en Configuration y establece Idle timeout (minutes) en 15:

   

Actualizar el tiempo de espera inactivo de TCP de la puerta de enlace NAT

1. En el portal de Azure, ve al grupo de recursos asociado con la VM del agente.

2. Haz clic en el elemento de puerta de enlace NAT asociado con la VM e IP. La puerta de enlace NAT asociada también aparece en el elemento de IP en Overview junto a Associated to.

3. Haz clic en Configuration y establece TCP idle timeout (minutes) en 15.

Actualizar el tiempo de espera de flujo de la VNET

1. En el portal de Azure, ve al grupo de recursos asociado con la VM del agente.

2. Haz clic en el elemento de VNET asociado con la VM:

   

3. En Overview, haz clic en Configure junto a Flow timeout:

   

4. Habilita Enable flow timeout y establece Flow timeout (minutes) en 15:

   

5. Haz clic en Save.

Reiniciar el agente

1. En el portal de Azure, reinicia la VM del agente.

2. Inicia el agente detenido (Windows | Linux).

Observabilidad

La observabilidad nativa no muestra datos

• Síntoma: Después de habilitar la observabilidad nativa, la pestaña Metrics de la página Agents de la Consola de administración no muestra datos, muestra datos incompletos o los gráficos permanecen vacíos después de esperar varios minutos.

• Posibles causas:

  • La sección [AgentMetrics] en jitterbit.conf no tiene Enabled=true, lo que impide que se ejecute el servicio de métricas.
  • No todos los parámetros requeridos en la sección [AgentCapability] están establecidos en true.
  • Los servicios del agente no se reiniciaron después de realizar cambios de configuración.
  • El host del agente no puede alcanzar la nube de Harmony, lo que impide que se envíen las métricas.
  • Antes de la versión 12.10 del agente, actualizar un agente privado de Windows cuyo puerto de PgBouncer ya era 6434 (consulta Puertos de PgBouncer) no actualizaba la conexión del servicio de métricas para que coincidiera, por lo que permanecía en el puerto antiguo 6432 y la métrica de PGBouncer podría reportarse incorrectamente.
  • Antes de la versión 12.9 del agente, instalar un agente privado como usuario no root en Linux no aprovisionaba PgBouncer, por lo que el servicio nunca se iniciaba y su estado siempre se mostraba como no saludable.

• Resolución:

  • Verifica que jitterbit.conf contenga todos los parámetros requeridos de las secciones [AgentMetrics] y [AgentCapability]. Consulta el ejemplo de configuración completo en configuración de observabilidad nativa.
  • Revisa metrics.log y metrics_service.log en el directorio de registros del agente para detectar errores. Estos registros documentan el estado del servicio de métricas e indican si se están recopilando y enviando métricas.
  • Reinicia los servicios del agente si se realizaron cambios de configuración.
  • Verifica que el host del agente pueda alcanzar la nube de Harmony. Consulta Agente sin conexión o inaccesible. Si el agente se conecta a través de un proxy, consulta Métricas del agente faltantes cuando el agente se conecta a través de un proxy HTTP.
  • Para un agente afectado por la discrepancia de puertos, actualiza a la versión 12.10 del agente o posterior, que corrige automáticamente el puerto de conexión de PgBouncer del servicio de métricas. Si la discrepancia persiste después de actualizar, contacta al soporte de Jitterbit para verificar el puerto.
  • Para un nuevo agente privado de Linux no root, usa la versión 12.9 o posterior, donde PgBouncer se aprovisiona correctamente durante la instalación. Actualizar un agente Linux no root existente a 12.9 o posterior no aprovisiona PgBouncer retroactivamente; el agente debe instalarse nuevamente.

Métricas del agente faltantes cuando el agente se conecta a través de un proxy HTTP

• Síntoma: El agente privado se conecta exitosamente a Harmony a través de un proxy HTTP configurado, pero la pestaña Métricas de la página Agentes de la Consola de Administración no muestra datos. El archivo metrics.log puede contener entradas como Client.Timeout exceeded while awaiting headers.
• Causa: El agente envía métricas sobre HTTPS utilizando una conexión separada que no hereda la configuración del proxy del agente. Si el proxy solo admite HTTP o no está configurado para el tráfico de métricas del agente, las métricas no pueden llegar a Harmony aunque el agente mismo se conecte exitosamente.
• Resolución:
  1. Confirma que el proxy admita HTTPS. Las métricas del agente se envían sobre HTTPS, por lo que un proxy que solo maneja tráfico HTTP las bloquea. Habilitar HTTPS en el proxy resuelve el problema.
  2. Si no puedes habilitar HTTPS en el proxy, o las métricas siguen faltando después de habilitarlo, el tráfico de métricas del agente necesita su propia configuración de proxy, separada de la del agente. Contacta al soporte de Jitterbit para configurarlo.

El agente Datadog falla al iniciarse después de la instalación en Docker

• Síntoma: Después de instalar el agente Datadog dentro de un contenedor Docker como parte de la configuración de observabilidad de Datadog, el agente Datadog falla al iniciarse.
• Causa: Un problema conocido de Datadog causa que el agente falle al iniciarse cuando el archivo de configuración del agente de seguridad no existe.

• Resolución: Copia el archivo de configuración del agente de seguridad de ejemplo:

  cp /etc/datadog-agent/security-agent.yaml.example /etc/datadog-agent/security-agent.yaml
  

  Luego inicia el agente Datadog. Ten en cuenta que en Docker, el agente Datadog no se inicia automáticamente con el contenedor y debe iniciarse manualmente después de cada inicio del contenedor:

  sudo datadog-agent run
  

Problemas del sistema y del SO

Error del servidor Apache: No hay ConfigArgs instalados

• Síntoma: El agente devuelve:

  No Installed ConfigArgs for the Service "Jitterbit Apache Server"
  

• Causa: La cuenta que ejecuta el servidor Apache de Jitterbit no tiene acceso completo al directorio de instalación de Jitterbit.

• Resolución: Otorga a la cuenta de servicio acceso completo a la carpeta de instalación de Jitterbit y reinicia los servicios.

Apache/Tomcat: APPARENT DEADLOCK

• Síntoma: Bajo carga sostenida, el agente deja de procesar operaciones y puede mostrarse como detenido en la Consola de Administración. El registro del agente contiene:

  ThreadPoolAsynchronousRunner: APPARENT DEADLOCK
  

  El registro también puede mostrar An existing connection was forcibly closed by the remote host para la base de datos PostgreSQL del agente. Reiniciar el agente restaura la operación normal temporalmente, después de lo cual el bloqueo se repite bajo carga.

• Posibles causas:

  • El grupo de conexiones de base de datos del agente se bloquea cuando la base de datos PostgreSQL interna se queda sin conexiones disponibles bajo carga pesada.
  • El grupo de conexiones de base de datos Java del agente (mostrado como c3p0 en el registro) no puede recuperarse después de que se pierda brevemente una conexión de base de datos, por ejemplo durante una interrupción de red transitoria, aunque PostgreSQL en sí permanece saludable y receptivo con tiempos de espera predeterminados.
  • Los procesos Jitterbit obsoletos están reteniendo hilos y conexiones de base de datos. Esto puede ocurrir cuando se actualiza un agente mientras las operaciones aún se están ejecutando, o cuando los servicios se detienen sin que todos los procesos Jitterbit terminen correctamente.
  • El host del agente está sobrecargado por actividad máxima, o su CPU está siendo limitada. Por ejemplo, una instancia en la nube ampliable (como un tipo AWS t3) limita su CPU una vez que se agotan sus créditos de ráfaga, lo que puede privar de recursos a PostgreSQL interno bajo carga.

• Resolución:
  • Detén todos los servicios de Jitterbit, finaliza cualquier proceso de Jitterbit que aún esté en ejecución y luego reinicia los servicios para limpiar el bloqueo.
  • Si el bloqueo está en el grupo de conexiones Java (c3p0) y PostgreSQL en sí está en buen estado, cambia el agente a su grupo de conexiones C++ interno configurando UseInternalPooling=true en la sección [DbInfo] de jitterbit.conf y luego reinicia el agente. El grupo interno se recupera de conexiones perdidas u obsoletas de manera más confiable. En instalaciones nuevas de agentes privados de Windows versión 12.5 y posteriores, esto ya está habilitado de forma predeterminada.
  • Reduce la carga en el agente: programa operaciones para evitar picos de actividad máxima, agrega agentes al grupo de agentes para equilibrio de carga y confirma que el host cumple con los requisitos del sistema. Para hosts en la nube, utiliza un tipo de instancia con rendimiento de CPU sostenido (no ampliable).
  • Antes de actualizar un agente, detén el drenaje y permite que terminen las operaciones en ejecución, de modo que ningún proceso quede reteniendo conexiones de base de datos durante la actualización. En entornos ocupados, permite tiempo adicional para que se complete el drenaje.

Apache se bloquea inesperadamente bajo carga concurrente

• Síntoma: Bajo carga concurrente, el proceso Apache del agente se bloquea y se reinicia inesperadamente, y el agente puede mostrarse brevemente como detenido o reiniciándose en la Consola de Administración. Las operaciones que se estaban ejecutando en ese momento pueden fallar o quedar en un estado incompleto.
• Posibles causas:
  • Un script utiliza llamadas anidadas de RunOperation para ejecutar una operación secundaria de forma sincrónica (la predeterminada) desde una operación principal, y ambas operaciones leen o escriben la misma variable global al mismo tiempo.
  • Una transformación está configurada con fragmentación y múltiples subprocesos, y un subproceso termina de ejecutarse antes que otro subproceso que comenzó al mismo tiempo.
  • Múltiples operaciones con generación de datos de entrada y salida de componentes habilitada se ejecutan al mismo tiempo.
• Resolución: Actualiza el agente privado a la versión 12.10 o posterior, que resuelve estos problemas. No existe solución alternativa en versiones anteriores.

El servicio de limpieza no puede eliminar archivos de registro bloqueados en Windows

• Síntoma: Los archivos de registro en un agente privado de Windows crecen indefinidamente y el servicio de limpieza no los elimina. El registro del servicio de limpieza reporta un error como:

  Failed to remove file, retries (10) exhausted: '...\jitterbit tomcat server-stdout.<date>.log'. Reason: The process cannot access the file because it is being used by another process.
  

• Posibles causas:

  • Un proceso del agente mantiene el archivo abierto. En Windows, el servicio de limpieza no puede eliminar un archivo que está en uso, y Tomcat mantiene abiertos sus archivos de registro stdout y stderr mientras se ejecuta.
  • Software de terceros (antivirus o un agente de monitoreo) mantiene un bloqueo en los archivos del directorio de registro del agente.

• Resolución:

  • Edita CleanupRules.xml para acortar la retención (FileAge) de los directorios de registro afectados, de modo que los archivos se eliminen rápidamente una vez que dejen de estar en uso. Reinicia el agente después de editar el archivo.
  • Excluye los registros de Tomcat stdout y stderr continuamente escritos de las reglas de limpieza, de modo que el servicio no reintente repetidamente archivos que permanecen bloqueados mientras se ejecuta el agente.
  • Si hay software de terceros involucrado, agrega los directorios de instalación y registro de Jitterbit a su lista de exclusión.
  • Si los registros siguen creciendo incluso con reglas de limpieza válidas, contacta al soporte de Jitterbit.

Linux: Los servicios del agente no se inician después de reiniciar ("postmaster.pid no existe")

• Síntoma: Después de reiniciar un host de agente privado en Linux, los servicios del agente no se inician. Al ejecutar sudo jitterbit status se muestran el planificador y otros servicios sin ejecutarse, y los registros del agente (o consola) incluyen errores como:

  postmaster.pid does not exist
  

  reindexdb: could not connect to database template1: could not connect to server: No such file or directory
  

• Causa: Los permisos de archivo en el directorio de datos de PostgreSQL incluido son demasiado permisivos. PostgreSQL requiere que el directorio de datos sea 700 (solo propietario). Si los permisos son más amplios (por ejemplo, 755 o 777), PostgreSQL se niega a iniciarse, lo que impide que el resto del agente se inicie.

• Resolución:

  1. Confirmar que /opt/jitterbit y sus subdirectorios son propiedad del usuario y grupo jitterbit:

     sudo chown -R jitterbit:jitterbit /opt/jitterbit
     

  2. Establecer el directorio de datos de PostgreSQL en 700:

     sudo chmod 700 /opt/jitterbit/DataInterchange/pgsql/data
     

  3. Iniciar los servicios del agente:

     sudo /etc/init.d/jitterbit start
     

Linux: El antivirus elimina PgBouncer, el agente no se autentica en la base de datos incluida

• Síntoma: Después de migrar un agente privado en Linux a un nuevo host (o realizar una instalación limpia), los servicios del agente no se inician. El archivo postgresql.log muestra:

  [FATAL] password authentication failed for user "jitterbit"
  

  El registro del agente muestra que no puede conectarse a la base de datos. El error persiste incluso después de desinstalar e reinstalar completamente.

• Causa: Un producto antivirus basado en host o de protección de puntos finales detecta el binario de PgBouncer incluido como sospechoso y lo elimina o pone en cuarentena. Sin PgBouncer, el agente no puede autenticarse en su base de datos PostgreSQL interna.

• Resolución:

  1. Desactivar temporalmente el antivirus o el producto de protección de puntos finales en el host del agente.
  2. Agregar el directorio de instalación de Jitterbit (típicamente /opt/jitterbit) a la lista de exclusión del antivirus.

  3. Reinstalar el agente. En RHEL/CentOS:

     sudo dnf reinstall jitterbit-agent
     

  4. Iniciar los servicios del agente y confirmar el funcionamiento normal, luego reactivar el antivirus con la exclusión en su lugar.

Los escaneos de seguridad marcan log4j-over-slf4j.jar como una vulnerabilidad de Log4j 1.x

• Síntoma: Un escaneo de seguridad de una instalación de agente privado marca archivos como log4j-over-slf4j-1.7.21.jar como una vulnerabilidad de Log4j 1.x fuera de soporte.
• Resolución: No se requiere ninguna acción. log4j-over-slf4j.jar no es Log4j 1.x. Es parte del marco de registro SLF4J y actúa como un puente que redirige las llamadas de bibliotecas de terceros escritas contra la API de Log4j 1.x al marco de registro actual y compatible del agente. El archivo no contiene el código vulnerable de Log4j 1.x. Su presencia es la mitigación del agente contra la exposición de Log4j 1.x, no una instancia de la vulnerabilidad.

Docker

General

Los siguientes puntos se aplican a problemas relacionados con Docker:

• Un agente privado de Docker no se iniciará si el directorio conf contiene tanto un archivo credentials.txt como un archivo register.json.

• La ejecución de agentes privados en Kubernetes no está oficialmente certificada por Jitterbit, y Jitterbit no ha validado una configuración lista para producción en Kubernetes. El gráfico de Helm y los pasos de Kubernetes se proporcionan solo como punto de partida para pruebas o desarrollo adicional.

El agente falla al reiniciarse con errores de autenticación después de la desregistración

• Síntoma: Un agente configurado con deregisterAgentOnDrainstop=true (o la variable de entorno AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP) falla al reiniciarse después de detenerse. Esto aplica a agentes Docker que utilizan un volumen persistente para /opt/jitterbit/Resources, y a agentes Linux no containerizados.

• Causa: Cuando el agente se detiene con deregisterAgentOnDrainstop=true, se desregistra de Harmony pero el archivo credentials.txt ahora inválido permanece en el disco. Al reiniciar, el agente intenta utilizar las credenciales obsoletas y falla en la autenticación.

  Nota

  A partir de la versión 12.4 del agente Docker, reiniciar el contenedor cuando deregisterAgentOnDrainstop=true está habilitado desregistra automáticamente el agente existente y registra uno nuevo. Los pasos a continuación aplican a agentes Docker en versiones anteriores, y a agentes Linux en cualquier versión.

• Resolución: Elimina el archivo credentials.txt obsoleto y luego reinicia el agente para activar un nuevo registro.

  En un agente Linux no containerizado, elimina el archivo directamente:

  rm /opt/jitterbit/Resources/credentials.txt
  

  En un agente Docker, elimina el archivo del volumen montado:

  docker run -i --rm -v VOLUME_NAME:/opt/jitterbit/Resources jitterbit/agent rm -i /opt/jitterbit/Resources/credentials.txt
  

  Reemplaza VOLUME_NAME con el nombre del volumen Docker bajo el cual está montado /opt/jitterbit/Resources.

Servicio de escucha

"El clúster no ha alcanzado el tamaño mínimo requerido"

• Síntoma: Las operaciones que utilizan el servicio de escucha fallan con:

  Failed to enable events for operation. Cluster has not met the minimum required size.
  

• Posibles causas:

  • Muy pocos agentes del grupo de agentes están ejecutándose y unidos al clúster. Para un grupo de \(N\) agentes, contados independientemente de si cada agente está ejecutándose, \((N / 2) + 1\) agentes (redondeados hacia abajo) deben estar ejecutándose y formar parte del clúster.
  • Uno o más agentes perdieron su conexión al clúster y no pudieron reconectarse, lo que redujo el número de agentes ejecutándose y unidos por debajo del \((N / 2) + 1\) requerido.
  • Una interrupción de red dividió el grupo de agentes en múltiples clústeres más pequeños. Por ejemplo, en un grupo de 4 agentes, una división de red puede producir dos clústeres de 2 agentes cada uno; ninguno cumple con el \((N / 2) + 1\) requerido de 3, por lo que ambos reportan el error aunque cada agente esté ejecutándose.

• Resolución:

  • Confirma que \((N / 2) + 1\) de los agentes del grupo están ejecutándose y forman parte del clúster, donde \(N\) es el número de agentes registrados en el grupo de agentes, independientemente de si cada uno está ejecutándose. Por ejemplo, un grupo de 4 agentes requiere 3, y un grupo de 5 agentes también requiere 3. Para ver qué agentes se han unido, utiliza la API REST del servicio de escucha para mostrar el estado del clúster.
  • Verifica que los puertos TCP 5701 y 5801 estén abiertos entre todos los hosts de agentes y no estén bloqueados por reglas de antivirus o firewall.
  • Si el clúster está inactivo y los mensajes permanecen sin procesar con persistencia habilitada, restaura el clúster manualmente. Consulta Restauración del clúster después de una falla del agente.

  Nota

  Se recomienda un número impar de agentes en el grupo de agentes, pero no es obligatorio. Con un número par, una interrupción de red puede dejar el grupo dividido en dos mitades, ninguna de las cuales es lo suficientemente grande para mantener el clúster en funcionamiento.

Los mensajes del servicio de escucha no se entregan

• Síntoma: El mecanismo de reintentos del clúster descarta silenciosamente los mensajes no entregados después de un período configurado, lo que causa que las operaciones dependientes no se ejecuten.
• Resolución: Para extender la ventana de retención o evitar la eliminación, edita JITTERBIT_HOME/Resources/jitterbit-agent-config.properties y establece agent.sdk_framework.retry.deleteRetryableMessageAfter en un valor más alto (en minutos). Para retener todos los mensajes indefinidamente, establece el valor en -1. Reinicia el agente después de realizar los cambios.

Registro

Los registros de operación de API personalizada no aparecen

• Síntoma: Una operación activada por una API personalizada se ejecuta sin errores, pero no aparece ninguna entrada de registro en Studio ni en la página Runtime de la Consola de Administración.
• Causa: Cuando una API personalizada activa una operación, los registros de operación se generan solo cuando la operación no es exitosa. Las operaciones de API personalizada exitosas no producen ninguna entrada de registro de forma predeterminada.
• Resolución: Para capturar registros de operaciones de API personalizada exitosas, habilita el registro de depuración de operación para la operación. Ten en cuenta que API Manager tiene su propia vista de registro separada para solicitudes de API.

El registro de depuración de operación se detiene antes de la fecha de finalización seleccionada

• Síntoma: El registro de depuración de operación se habilitó con una fecha de finalización futura, pero los registros dejan de generarse antes de que se alcance esa fecha.
• Causa: En grupos de agentes en la nube, la fecha de finalización de la configuración de registro de depuración de operación no es confiable. Los registros pueden dejar de generarse antes de que finalice el período de tiempo configurado.
• Resolución: Vuelve a habilitar el registro de depuración de operación según sea necesario.

Los archivos de registro de depuración de operación no tienen datos .input o .output

• Síntoma: En un agente privado, una operación tiene el registro de depuración de operación habilitado con los datos de entrada y salida del componente activados. La carpeta de registro de depuración en DataInterchange/Temp/Debug contiene los archivos .jtr para cada paso, pero faltan los archivos de datos .input y .output correspondientes.

• Posibles causas:

  • El servicio de limpieza del agente está eliminando los archivos .input y .output antes de que se puedan revisar.
  • El agente se reinició mientras la operación aún se estaba ejecutando, por lo que los archivos nunca se escribieron completamente. Consulta Los datos de entrada/salida del componente no se generan para ese escenario.

• Resolución:

  1. En el host del agente, abre CleanupRules.xml en el directorio de instalación del agente.

  2. Encuentra la regla de limpieza para el directorio DataInterchange/Temp/Debug e incrementa el valor <FileAge NumDays = "2"...> a una ventana de retención más larga (por ejemplo, 7).

     <CleanupRule>
       <DirectoryPath SearchSubDirectory = "YES" >DataInterchange/Temp/Debug</DirectoryPath>
       <Pattern>*</Pattern>
       <FileAge NumDays = "7" Comparator = "GE"/>
       <FileSize Size = "0" Comparator = "GE"/>
     </CleanupRule>
     

  3. Reinicia los servicios del agente.

Los datos de entrada/salida del componente no se generan

• Síntoma: El registro de depuración de operación está habilitado con la generación de datos de entrada y salida del componente activada, pero no aparecen archivos de datos de entrada/salida para operaciones de agente privado.

• Resolución: Verifica el registro del servicio Verbose Log Shipper en el agente:

  <JITTERBIT_HOME>/VerboseLogShipper/verbose-log-shipper.out.log
  

  Si el registro muestra errores, reinicia el servicio Verbose Log Shipper. En Linux, esto se puede hacer sin un reinicio completo del agente:

  jitterbit stop verboselogshipper
  jitterbit start verboselogshipper
  

  En Windows y Linux, reiniciar todos los servicios del agente de Jitterbit también reinicia el servicio Verbose Log Shipper.