Solución de problemas del agente privado de Jitterbit

Esta página proporciona orientación para solucionar problemas comunes que se encuentran al instalar, ejecutar o gestionar un agente privado de Jitterbit. Comience con los pasos de diagnóstico a continuación, luego busque su error específico en la sección correspondiente. Contacte 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, consulte la guía de solución de problemas de Harmony.

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

Revisar el estado actual del agente en la Consola de Administración bajo Agentes > Privado, luego usarlo para reducir el problema. Para las definiciones completas de estado y cómo transicionan, ver Estado del agente.

Verificar los archivos de registro del agente

Los archivos de registro del agente son la fuente principal de información diagnóstica. Verifica el siguiente archivo en busca de errores relacionados con la conectividad, la salud del servicio y fallos en las operaciones:

• 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 diagnósticos que se ejecutan directamente en el host del agente:

• connection-check: Verifica la conectividad desde el agente a la nube de Harmony, servicios de Apache y Tomcat.
• service-status: Muestra el estado de ejecución de todos los servicios del agente (Apache, Tomcat, PostgreSQL, PgBouncer, VerboseLogShipper).
• generate-report: Crea un informe HTML diagnóstico y un archivo ZIP de todos los archivos de registro del agente, útil al escalar a soporte de Jitterbit. En los agentes de Linux, el informe actualmente omite datos de PostgreSQL; los agentes de 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 y conectividad del agente

Agente fuera de línea o inalcanzable

• Síntoma: La pestaña Privada de la Consola de Gestión Página de Agentes muestra el agente como Desconocido o Detenido, o Studio muestra un error de Agente No Ejecutándose o Inalcanzable.

• Causas posibles:

  • Los servicios de Jitterbit no están en ejecución.
  • Los servicios están en ejecución, 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 están en ejecución, inícielos:

    • Windows: Consulte Iniciar un agente de Windows.
    • Linux: Consulte Iniciar un agente de Linux.

    Si el servicio no se inicia, verifique lo siguiente en busca de mensajes de error:

    • Windows: C:\Program Files (x86)\Jitterbit Agent\log y el registro de Aplicaciones del Visor de Eventos 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 están en ejecución pero no pueden alcanzar la nube de Harmony, verifique lo siguiente:

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

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

  • Si los servicios del agente están saludables en el host (jitterbit status muestra todos los servicios en ejecución) pero el agente cambia repetidamente a Desconocido, o cicla entre Ejecutándose, Desconocido y Detenido, es probable que la conexión o el proceso del agente se esté interrumpiendo entre latidos. Verifique las siguientes posibles causas:

    • Un dispositivo de red (cortafuegos, puerta de enlace NAT o tiempo de espera de inactividad de VM en la nube) puede estar cerrando la conexión saliente del agente entre latidos. Intente reducir el intervalo de latido del agente (agent.heart.beat.interval). Para agentes alojados en la nube, consulte 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. Verifique si hay archivos de volcado de fallos OutOfMemoryError o hs_err_pid. Consulte Espacio de pila de Java: OutOfMemoryError.
    • Si los agentes fueron migrados recientemente a un nuevo sistema operativo reutilizando un grupo de agentes que anteriormente albergaba agentes en el antiguo SO, el grupo reutilizado puede ser la causa. Consulte El agente muestra Desconocido o Detenido después de reutilizar un grupo de agentes entre sistemas operativos.

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: La máquina host del agente puede haber sido duplicada a nivel de infraestructura (por ejemplo, un clon de VM, imagen de disco, plantilla de máquina o instantánea creada después de que el agente fue instalado y registrado). El host duplicado lleva las mismas credentials.txt del agente, por lo que ambos hosts se autentican en Harmony como el mismo agente y funcionan en paralelo, colisionando. Dos agentes no pueden ejecutarse simultáneamente bajo las mismas credenciales.
• Resolución:
  1. Confirma que hay un duplicado en ejecución. Detén el agente en el host que deseas conservar, 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 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 conservar.
  4. Verifica que el nuevo agente esté listado 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 antiguo agente usando Acciones > Eliminar.

Agente muestra Desconocido o Detenido después de reutilizar un grupo de agentes entre 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 como Desconocido o Detenido en la pestaña Privado de la página Agentes de la Consola de Administración, a pesar de que jitterbit status muestra los servicios en ejecución y las operaciones funcionan normalmente.
• Causa posible: Reutilizar un grupo de agentes del sistema operativo anterior puede dejar metadatos que interfieren con el reporte de estado para los nuevos agentes. El efecto es típicamente cosmético: los servicios y operaciones continúan funcionando 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í.

Fallo de sincronización del agente: los cambios del proyecto no se aplican

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

• Causas posibles:

  • La implementación utilizó Despliegue configurable, que despliega solo los flujos de trabajo y operaciones seleccionados. Cualquier parte del proyecto fuera de esa selección permanece en su versión previamente desplegada en el agente.
  • El componente no se utiliza en el flujo lógico de un flujo de trabajo desplegado. Los componentes no utilizados no se despliegan, por lo que una conexión que ninguna operación desplegada 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 los archivos del proyecto sincronizado se escribieran.

• Resolución:

  • Vuelve a desplegar el proyecto completo: en Studio, utiliza Desplegar, que despliega todas las operaciones del proyecto, en lugar de un Despliegue configurable de solo flujos de trabajo u operaciones seleccionadas.
  • Reinicia los servicios del agente para forzar una nueva sincronización de todos los proyectos desplegados.
  • Revisa los registros del agente en busca de 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 del proyecto sincronizado. Consulta Espacio en disco y acumulación de registros.

Operaciones retrasadas o en cola después del despliegue del proyecto

• Síntoma: Después de desplegar un proyecto en Studio, las operaciones desencadenadas no comienzan de inmediato, o aparece un breve retraso de operaciones en cola.
• Causa: El entorno está bloqueado mientras el agente sincroniza el proyecto desplegado. No se pueden ejecutar operaciones durante esta ventana.
• Resolución:
  1. Para medir cuánto tiempo duran los bloqueos de sincronización, escanea jitterbit-agent.log en busca de environment-deploy. Cada entrada de registro incluye el ID del entorno y la duración de la sincronización en milisegundos.
  2. Tiempos de sincronización consistentemente largos indican un proyecto grande o conectividad lenta a Harmony. Para reducir los tiempos de sincronización, consulta ajuste del rendimiento de sincronización del entorno.
  3. Si las duraciones de sincronización son consistentemente excesivas (más de unos minutos), contacta con soporte de Jitterbit.

Agente mostrando como incapaz

• Síntoma: Las operaciones enviadas al grupo de agentes se reintentan o retrasan en lugar de ejecutarse de inmediato. 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
  

• Causas posibles:

  • Cada hilo de trabajo en el motor de procesos del agente ya está en uso, por lo que el agente no puede aceptar otra operación hasta que un hilo se libere. El tamaño del grupo está configurado por MaxNumberOfWorkerThreads en la sección [ProcessEngine] de jitterbit.conf.
  • Se ha habilitado una métrica de capacidad opcional 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 por defecto y solo se aplican cuando se activan en la sección [AgentCapability] de jitterbit.conf. El uso de memoria se recopila solo en agentes de Windows, por lo que no contribuye al estado de capacidad en un agente de Linux, incluso cuando se habilitan las configuraciones de memoria. Apache solo atiende solicitudes de API, por lo que el uso de hilos de Apache es relevante solo en un agente que maneja APIs.
  • Un solo agente en el grupo está manejando más carga de la que puede soportar mientras que otros agentes en el grupo están inactivos o infrautilizados.

• Resolución: Revisa ProcessEngine.log en busca de largas secuencias de cambios en el estado de capacidad para confirmar que el agente está alternando entre estados incapaces, luego investiga lo siguiente:

  • Si muchas operaciones se ejecutan consistentemente al mismo tiempo, 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 configúralo de manera 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 desencadenante más probable. Si el uso de CPU o memoria está habilitado, revísalo antes de las métricas de hilos: cualquiera de los dos que cruce su umbral hace que el agente sea incapaz independientemente de la disponibilidad de hilos. En un agente de 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 de Capacidad de Recursos del Sistema, Hilos de Apache y Hilos de Tomcat en la pestaña Métricas de la página de Agentes 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 enmascarar un solo agente sobrecargado mientras que el resto del grupo parece saludable.
  • Si el grupo de agentes contiene múltiples agentes, revisa 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 dirigido a un agente capaz. Verifica que el balanceo de carga esté configurado correctamente para el grupo.
  • Si se alcanzan consistentemente los límites de recursos, agrega agentes al grupo para distribuir la carga.
  • Si la presión de memoria es el desencadenante, consulta Espacio de pila de Java: OutOfMemoryError.

Fallos de transformación: "No se pudo encontrar el archivo en el almacenamiento local de archivos"

• Síntoma: Una operación falla durante una transformación con un error que indica que falta un archivo en el almacenamiento local de archivos 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 importar un proyecto entre entornos.

• Resolución:
  1. Vuelva a ejecutar la operación. En la versión del agente 11.38 y posteriores, el agente se auto-repara esta condición: el error ocurre como máximo una vez por ID de archivo en un agente dado, y el agente restaura los metadatos faltantes en la próxima sincronización del entorno (la próxima ejecución de la operación o implementación). En la mayoría de los casos, volver a ejecutar la operación lo soluciona.
  2. Si el mismo archivo sigue fallando en múltiples ejecuciones en un agente actual, es probable que haya 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. Contacte a soporte de Jitterbit con el nombre de la operación fallida y el 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 de camino, con cualquiera 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ó. Más a menudo, el paso que falla es la configuración de PostgreSQL empaquetada con 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] Nombre de origen de datos no encontrado y no se especificó un controlador predeterminado, y la base de datos de PostgreSQL empaquetada y el servicio de Windows jitterbitpostgres pueden no estar completamente creados. El mensaje puede nombrar en su lugar una acción diferente, como InstallVerboseLogShipper.

• Causas posibles:

  • Un Microsoft Visual C++ Redistributable faltante o en conflicto (el PostgreSQL empaquetado lo requiere).
  • Caracteres prohibidos en la contraseña de PostgreSQL.
  • En una reinstalación, componentes de PostgreSQL sobrantes de un agente anterior. El desinstalador del agente no elimina PostgreSQL, el usuario de Windows jitterbitpostgres, ni sus entradas de 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 sobrantes del servicio de envío de registros detallados de un agente anterior. Al igual que con PostgreSQL, una desinstalación estándar no elimina el servicio de envío de registros detallados ni sus archivos, y estos restos pueden causar que la acción InstallVerboseLogShipper del instalador falle.

• Resolución:

  • Instale el Microsoft Visual C++ Redistributable de 64 bits para Visual Studio usando vc_redist.x64.exe (cubre Visual Studio 2015, 2017 y 2019) antes de instalar el agente, y manténgalo instalado, porque eliminarlo durante una limpieza también interrumpe la instalación.

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

    Nota

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

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

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

    Si la instalación aún falla después de una limpieza exhaustiva, contacta a soporte de Jitterbit.

Servicio de 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 de PostgreSQL (postgresql-x64-<VERSION>) ya no aparece en los Servicios de Windows, y los servicios del agente de Jitterbit no pueden iniciarse debido a una dependencia faltante.

• Causa: Esto ocurre con versiones de agentes privados anteriores a 11.59 / 12.3 cuando se ingresa una contraseña incorrecta durante la actualización y el instalador no puede revertir 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 la reentrada o cancelación sin afectar la instalación existente.

• Resolución:

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

  2. Vuelve a registrar el servicio de PostgreSQL:

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

     Reemplace <VERSION> con el número de versión de PostgreSQL. Para encontrarlo, consulte la versión de PostgreSQL incluida con el agente privado.

  3. Inicie los servicios de PostgreSQL y PgBouncer:

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

  4. Inicie todos los servicios del agente Jitterbit:

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

  5. Una vez que el agente esté en funcionamiento, restablezca las contraseñas de administrador y de cuenta de servicio de PostgreSQL antes de intentar nuevamente la actualización.

TFA impide la instalación del agente 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: Desactive temporalmente la TFA, instale el agente y luego vuelva 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, accesible 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 al agente en un estado roto.
• Resolución: Desinstale completamente el agente y luego reinstale el software del agente.

La instalación no root de Linux falla

• Síntoma: El instalador Linux Redhat Non-Root (x64) falla.
• Resolución: Verifique lo siguiente:
  • El usuario no root tiene privilegios de sudo. Un administrador del sistema debe agregar al usuario al grupo wheel. Para verificar la membresía actual del grupo, ejecute groups.
  • Al iniciar sesión como el usuario jitterbit, la variable de entorno JITTERBIT_HOME está configurada en la ubicación de instalación:

echo $JITTERBIT_HOME

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

. /opt/jitterbit/scripts/set.env

• Si el instalador falla con un error OPENSSL_3.4.0, este es un problema conocido en RHEL 9.7 y versiones posteriores. Consulta La instalación de agentes privados no root en RHEL 9.7 y posteriores muestra un error de OpenSSL en los problemas conocidos de agentes privados para una solución alternativa.

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

• Síntoma: Una conexión a la base de datos falla porque el controlador JDBC requerido no está instalado en el agente, con un error como No se encontró un controlador adecuado para jdbc:<subprotocol>://....
• Causa: Jitterbit no incluye todos los controladores JDBC. El controlador requerido debe instalarse manualmente.
• Resolución: Instala el controlador requerido manualmente: regístralo en JdbcDrivers.conf y copia el archivo .jar del controlador a JITTERBIT_HOME/tomcat/drivers/lib/, luego reinicia el agente. Para los pasos completos, consulta 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 libera una nueva versión del conector o después de desplegar un proyecto que utiliza un conector basado en SDK de Conector:

  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
  

• Causas posibles:

  • 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 Probar. Esto activa al agente para descargar la última versión del conector desde la nube.
  • Si el conector aún no se descarga, verifica si la política organizacional Deshabilitar actualización automática de conectores está habilitada. Cuando está habilitada, el botón Probar no descarga versiones de conectores. Consulta Gestión de Agentes.
  • Para descargar el conector sin cambiar la política, ve a la página de la Consola de Gestión Agentes, selecciona el grupo de agentes y elige Acción > Actualizar conectores. Esto fuerza una actualización de conectores en todo el grupo y no se ve afectado por la política Deshabilitar actualización automática de conectores.
  • Para agentes privados, verifica que el host del agente pueda alcanzar la nube de Harmony. Consulta Agente fuera de línea o inalcanzable.

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

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

  Could not connect to Jitterbit Harmony cloud
  

• Causas posibles:

  • 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 Servidor proxy para agentes privados de Jitterbit.

• Resolución:

  1. Configura el proxy durante la configuración del agente para que el instalador pueda acceder a la nube de Harmony a través de él, proporcionando las credenciales del proxy (y el dominio NTLM, si el proxy lo requiere). Consulta Configurar un proxy durante la configuración del agente.
  2. Si el registro sigue fallando a través del proxy, pide a tu equipo de red que permita los dominios y direcciones IP de Jitterbit a través del proxy, o que los omita. Las URL específicas de la región de Harmony están documentadas en Información de lista permitida.
  3. Vuelve a ejecutar el instalador una vez que el proxy esté configurado o el host pueda acceder a la nube de Harmony.

Problemas de rendimiento y recursos

Espacio en el heap de Java: OutOfMemoryError

• Síntoma: Las operaciones que procesan archivos grandes o que ejecutan muchas operaciones de manera concurrente fallan con:

  java.lang.OutOfMemoryError: Java heap space
  

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

• Resolución:
  1. Aumenta el tamaño máximo del heap de Java del agente privado. Consulta Memoria del heap de Tomcat para saber cómo cambiar el valor de -Xmx (por ejemplo, de -Xmx1024m a -Xmx4096m).
  2. Reinicia los servicios del agente después de hacer 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 donde califiquen.
  4. Si observabilidad nativa está habilitada, utiliza el gráfico de Capacidad de Recursos del Sistema en la pestaña de Métricas de la página de Agentes de la Consola de Gestión para monitorear el uso de memoria a lo largo del tiempo y ajustar el tamaño del heap para 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 o que las operaciones fallen con errores de permisos. Los archivos de registro y temporales se acumulan en los directorios del agente, especialmente en los agentes que procesan altos volúmenes.
• Resolución:
  • Verifique el espacio en disco disponible en el host del agente.
  • Identifique archivos grandes. Los registros del agente y los archivos temporales se encuentran en JITTERBIT_HOME/log, JITTERBIT_HOME/tomcat/logs (catalina.out), y JITTERBIT_HOME/DataInterchange/Temp. Consulte Archivos de registro para la lista completa. Un solo archivo de registro puede crecer a varios gigabytes cuando un componente registra en exceso (por ejemplo, un conector detallado inunda catalina.out) o cuando un error se repite (por ejemplo, una conexión a la base de datos fallida que se repite en ProcessEngine.log). Limpie los archivos de gran tamaño si el espacio es críticamente bajo; limpiar el archivo y reiniciar el agente también puede detener el error subyacente.
  • Confirme que el servicio de limpieza esté en funcionamiento y que se respete su retención. En la sección [FileCleanup] de jitterbit.conf, verifique que AutoStart esté en true y revise FrequencyInHours. La retención por directorio se establece en CleanupRules.xml utilizando NumDays o NumOfHours.
  • Si el servicio de limpieza no puede eliminar archivos de registro activos (Tomcat mantiene sus registros stdout y stderr abiertos en Windows), aumente el FileAge para ese directorio en CleanupRules.xml a al menos un día para que la limpieza no apunte a archivos que aún se están escribiendo.
  • Si grandes archivos de volcado de fallos .dmp están consumiendo el disco, consulte Los archivos de mini-volcado 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 Motor de Procesos se detienen y reinician en un bucle sin permanecer en línea, y las operaciones fallan con errores como El servicio de Tomcat no está en ejecución. Si jitterbit status muestra todos los servicios saludables en el host pero el estado mostrado solo fluctúa entre Ejecutándose, Desconocido y Detenido, eso es un problema de conectividad en lugar de un bucle de bloqueo. Consulte Agente fuera de línea o inalcanzable.

• Causas posibles:

  • Un proceso huérfano de Jitterbit de una ejecución anterior (un proceso de Tomcat, Motor de Procesos o programador) 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 ciclea.
  • El host se queda sin memoria y el sistema operativo termina el proceso. Esto puede suceder cuando el host tiene muy poca memoria para la carga de trabajo, o cuando el límite de memoria de un contenedor está configurado demasiado bajo.
  • El host del agente tiene poco espacio en disco, o la base de datos interna de PostgreSQL ha crecido lo suficiente como para fallar al iniciar.
  • El Motor de Procesos se está bloqueando 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 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 de Jitterbit que haya quedado antes de reiniciarlo. Con el agente detenido, verifica si hay procesos errantes: en Linux, ejecuta ps aux | grep -E 'tomcat|jitterbit' y kill cualquier ID de proceso restante; en Windows, finaliza cualquier proceso errante de Jitterbit o Tomcat en el Administrador de tareas. Inicia el agente nuevamente una vez que no queden procesos.
  • Verifica eventos de falta de memoria. En Windows, revisa los registros de Aplicación y Sistema en Visor de eventos; en Linux, ejecuta journalctl -u jitterbit o revisa /var/log/syslog para eventos del OOM killer. Si el host se está quedando sin memoria, aumenta la memoria disponible (o el límite de memoria del contenedor). Consulta Espacio de pila de Java: OutOfMemoryError.
  • Verifica el espacio en disco y la base de datos interna. Un disco lleno o una base de datos de PostgreSQL inflada pueden hacer que los servicios se bloqueen 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 de Métricas de la página de Agentes de la Consola de Administración y revisa los gráficos de servicio de Tomcat y Motor de Procesos para identificar cuándo comenzaron a fallar los servicios.

Operaciones que se agotan o ignoran las configuraciones de tiempo de espera

• Síntoma: Las operaciones se ejecutan indefinidamente o más tiempo del esperado. Para las operaciones activadas por API, las configuraciones de tiempo de espera configuradas en Studio parecen no tener efecto, y las operaciones pueden permanecer atascadas en un estado de Ejecutándose.

• Causas posibles:

  • Por defecto, las operaciones activadas por las APIs del Administrador de API ignoran las configuraciones 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 para la operación, por lo que las operaciones se ejecutan sin un límite de tiempo estricto.

• Resolución:

  1. Para hacer cumplir la configuración de tiempo de espera de operaciones para operaciones activadas por API, establece EnableAPITimeout=true en la sección [Settings] de jitterbit.conf.
  2. Para limitar el tiempo total de ejecución 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.

Rendimiento del agente sin cambios 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.

• Causas posibles:

  • Solo se cambió max.concurrent.requests. El rendimiento del agente también depende de los grupos de hilos de Tomcat y Apache, así como de los grupos de conexiones HTTP, por lo que aumentar esta configuración sin escalar las otras simultáneamente no produce ningún beneficio.
  • El host del agente no tiene suficiente CPU o memoria para la concurrencia adicional, o el agente está entrando en un estado incapaz bajo carga.

• Resolución:

  • Sigue el procedimiento completo de ajuste en lugar de cambiar solo max.concurrent.requests, escalando las configuraciones relacionadas de grupos de hilos y grupos de conexiones juntos. Consulta Rendimiento y ajuste del agente.
  • Confirma que el host del agente tiene suficiente margen de CPU y memoria para la mayor concurrencia. Si el agente se bloquea o entra en un estado incapaz bajo carga, consulta Bucle de reinicio del servicio del agente y Espacio de pila de Java: OutOfMemoryError.

Desaceleración de la transformación XML después de actualizar a la versión 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 gran arreglo tarda más en ejecutarse que en la versión 11.44. La desaceleración es específica para las rutas de mapeo que utilizan la notación # para iterar sobre cada elemento de un gran arreglo (aproximadamente varios cientos a unos pocos miles de registros). Las transformaciones que no iteran sobre grandes arreglos 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 a las transformaciones que iteran sobre un gran arreglo, porque el mapeo atraviesa repetidamente los datos analizados.
• Resolución:
  • Revisa 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, elimina el # y vuelve a implementar. Eliminar # mapea solo el primer elemento, así que aplica esto solo donde no se requiera iterar sobre el arreglo completo.
  • Si el mapeo debe iterar sobre el arreglo completo, procesa menos registros por ejecución dividiendo un gran conjunto de datos en lotes más pequeños, de modo que cada transformación atraviese un arreglo más pequeño.

Los archivos mini-dump de JVM llenan el disco del agente

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

• Causas posibles:

  • El recolector de estadísticas de disco AgentStats del agente bloquea la JVM mientras recopila métricas de disco. Esto afecta a los agentes en versiones anteriores a la 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: Actualice el agente privado a la versión 11.49 o posterior, lo 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 del disco, puede desactivar esa recopilación como una solución alternativa (el flag DiskStatsEnabled está disponible en el agente 11.44.1 y versiones posteriores):

  1. En jitterbit.conf, agregue:

     [AgentStats]
     DiskStatsEnabled=false
     

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

  3. Si está en 11.47 o 11.48 y los archivos de bloqueo continúan, actualice a 11.49 o contacte a soporte de Jitterbit para una solución alternativa.

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 interna PostgreSQL del agente privado, o los servicios internos del agente no pueden iniciarse porque se ha alcanzado su límite de conexiones. Los fallos repetidos también pueden inundar ProcessEngine.log, haciéndolo 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 interno de max_connections de PostgreSQL, o el límite de max_db_connections de PgBouncer, es demasiado bajo para la carga de trabajo del agente.
  • Las operaciones se están acumulando bajo una carga pesada o una desaceleración de red o de punto final, manteniendo las conexiones a la base de datos hasta que se agote el grupo de PgBouncer (query_wait_timeout).
  • En un agente de Windows, IP Helper está interfiriendo con las conexiones locales de la base de datos del agente.

• Resolución:

  • Las versiones recientes del agente vienen con límites de conexión de PostgreSQL y PgBouncer más altos por defecto, así que primero confirme que el agente esté en una versión actual. Si un agente actual aún agota su límite de conexiones, contacte a soporte de Jitterbit para aumentarlo bajo la guía del soporte. Las instancias de PostgreSQL y PgBouncer empaquetadas deben cambiarse solo bajo la guía del soporte.
  • Si los límites ya son adecuados, investigue qué está manteniendo las conexiones abiertas: revise la carga del host del agente y cualquier lentitud en la red o en el punto final que esté acumulando operaciones.
  • En un agente de Windows, desactive IP Helper. Consulte problema de IPv6 en Windows.

PostgreSQL empaquetado en Linux utiliza MD5 en lugar de SCRAM-SHA-256

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

• Causas posibles:

  • MD5 es la encriptación de contraseña predeterminada para el PostgreSQL empaquetado 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 de 12.6 o 12.7, el instalador te solicita restablecer la encriptación a MD5 o mantener SCRAM-SHA-256; consulta Actualizar un agente de Linux.
  • Editar pg_hba.conf y postgresql.conf por sí solo no completa el cambio. PgBouncer también debe ser reconfigurado con el hash del verificador SCRAM, o el agente no podrá iniciarse.

• Resolución: Para cambiar un agente privado de Linux a SCRAM-SHA-256, sigue la guía de SCRAM en PostgreSQL. SCRAM-SHA-256 es un método de autenticación más fuerte, mientras que MD5 es más eficiente, por lo que el cambio es deliberado y en múltiples pasos: la guía reconfigura el PostgreSQL empaquetado, actualiza las contraseñas de los usuarios y reconfigura PgBouncer con el nuevo hash. Reconfigurar la instancia empaquetada es la forma soportada de habilitar SCRAM. No reemplaces la instancia empaquetada con tu propio servidor PostgreSQL para obtener SCRAM: los agentes que utilizan una instancia de PostgreSQL diferente a la empaquetada no son soportados.

PostgreSQL: Apagado rápido administrativo

• Síntoma: Todas las operaciones fallan porque la base de datos del agente no está disponible (las operaciones pueden quedar 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 informar FATAL: terminando conexión debido a un comando del administrador.

• Causas posibles:

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

• Resolución:

  • Reinicie los servicios de PostgreSQL y del agente de Jitterbit (o reinicie el host del agente) para recuperarse. Si las operaciones siguen atascadas en un estado Pendiente o Ejecutándose después de que PostgreSQL esté de vuelta, contacte a soporte de Jitterbit, ya que el grupo de conexiones de la base de datos del agente puede no haberse recuperado.
  • Identifique qué detuvo PostgreSQL: revise el registro de eventos del sistema operativo (en Windows, Visor de eventos) alrededor del momento de la falla en busca de reinicios, actualizaciones, tareas programadas, bloqueos de servicios o herramientas de respaldo y monitoreo que reinician servicios. Prevenga o reprograma lo que lo esté deteniendo y configure el servicio de PostgreSQL para reiniciarse automáticamente en caso de falla.
  • Verifique la CPU y la memoria del host del agente. Si los servicios de Jitterbit se están bloqueando bajo carga, consulte Bucle de reinicio del servicio del agente y Espacio de pila de Java: OutOfMemoryError.

Red y conectividad

Fallo en el apretón de manos del certificado (TLS)

• Síntoma: Las operaciones que se conectan a puntos finales seguros fallan durante el apretón de manos 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
  

• Causas posibles:

  • El punto final utiliza la renegociación heredada de TLS, que el agente bloquea por defecto.
  • 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 la versión 12.x envían diferentes bibliotecas de seguridad, por lo que un punto final que no logra conectarse en un agente 11.x puede tener éxito en un agente 12.x.
  • El certificado del punto final (o uno de sus intermedios) no es confiable 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, ejecute lo siguiente para confirmar qué versión de TLS negocia el punto final y si el apretón de manos tiene éxito a nivel de red:

  openssl s_client -connect hostname:port
  

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

  • Si el error es unsafe legacy renegotiation disabled, establezca AllowUnsafeLegacyRenegotiation=true en la sección [Settings] de jitterbit.conf y reinicie el agente. Esta configuración requiere la versión 11.39 o posterior del agente.
  • 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 intermedios) no está en el almacén de confianza cacerts del JRE del agente. Use keytool -import en el cacerts del JRE del agente (contraseña predeterminada changeit) para importar el/los certificado(s) faltante(s), luego reinicie los servicios del agente. Para una base de datos de SQL Server a la que se accede a través de una conexión Database, también puede 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. Consulte SQL Server: Connection fails with a PKIX certificate path error.
  • Si persiste un fallo en la negociación o apretón de manos de TLS, particularmente en un agente 11.x, actualice a un agente 12.x actual, que incluye bibliotecas de seguridad actualizadas y un almacén de confianza de certificados actualizado.

La conexión del sandbox de Salesforce falla con un desajuste de certificado

• Síntoma: Una conexión de agente privado a un punto final que requiere Server Name Indication (SNI) falla con un desajuste de certificado, mientras que la misma conexión tiene éxito 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 sandbox de Salesforce que termina en .sandbox.my.salesforce.com:

  El certificado para <your-domain.sandbox.my.salesforce.com> no coincide con ninguno de los nombres alternativos del sujeto: ...
  

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

• Causa: El apretón de manos TLS no incluye la extensión SNI, por lo que el servidor devuelve un certificado predeterminado en lugar del que corresponde al host solicitado. Para un sandbox de Salesforce, el balanceador de carga devuelve el certificado de producción, cuyos nombres no cubren *.sandbox.my.salesforce.com. SNI se envía por defecto, 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   # certificado cuando se envía SNI
     openssl s_client -connect HOST:443                    # certificado cuando se omite SNI
     

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

  2. 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 de 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.

  3. Si SNI sigue faltando después de eso, un dispositivo de red, proxy o pila de red de VM entre el agente y el punto final lo está eliminando. Tu equipo de red debe permitir la extensión SNI.

  Si la conexión también falla desde un grupo de agentes en la nube, SNI no es la causa. El certificado del servidor puede no listar el host en sus Nombres Alternativos del Sujeto. Para Salesforce, agrega la URL de MyDomain del sandbox al certificado de Salesforce, o consulta Desajuste de Nombres Alternativos del Sujeto del Certificado (SAN).

FTP: La conexión de datos ha agotado el tiempo

• Síntoma: El inicio de sesión FTP tiene éxito, pero la lista de archivos o la transferencia de archivos se detiene y agota el tiempo.

• Causas posibles:

  • El modo de conexión FTP (activo vs. pasivo) es incompatible con la configuración de la red o del 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 FTP, activa o desactiva la casilla de verificación Modo Pasivo. El modo pasivo es generalmente preferido 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 los 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 de Windows a pesar de que 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].

Falta la configuración SSH de SFTP o está en la sección incorrecta de jitterbit.conf

• 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. Las configuraciones de clave SSH añadidas al jitterbit.conf local también pueden dejar de tener efecto después de que el agente se reinicie.

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

• Causas posibles:

  • La configuración del agente remoto está habilitada (está activada por defecto), por lo que los ajustes gestionados a través de la pestaña Configuración de Jitterbit en la Consola de Gestión tienen prioridad. Los ajustes de clave SSH añadidos solo al jitterbit.conf local pueden no tener efecto o pueden no ser retenidos después de que el agente se reinicie.
  • Los ajustes de clave SSH (PrivateKeyFile, PrivateKeyPassphrase, PublicKeyFile) están en la sección incorrecta. Las versiones más nuevas del agente analizan estrictamente e ignoran los ajustes SSH colocados fuera de la sección [SSH] (por ejemplo, bajo [SSL]).

• Resolución:

  1. Si la configuración remota está habilitada, añade los ajustes de clave SSH allí: abre el panel de Detalles del grupo de agentes para el grupo de agentes, selecciona la pestaña Configuración de Jitterbit y añádelos bajo la sección SSH. Consulta Configuración de Jitterbit.
  2. Si el jitterbit.conf local es la fuente de configuración, confirma que los ajustes de clave SSH estén colocados 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 paso, formato de clave), consulta SFTP "Acceso denegado. Fallo de autenticación." al usar claves SSH.

Fallo de autenticación SFTP a un servidor específico (desajuste de cifrado cURL)

• Síntoma: Una conexión SFTP utilizando autenticación de clave SSH falla en un agente privado con Acceso denegado. Fallo de autenticación., pero otras conexiones SFTP desde el mismo agente (usando la misma clave) tienen éxito, y conectarse al servidor que falla desde la línea de comandos del sistema operativo también tiene éxito.

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

• Causa: El servidor SFTP requiere cifrados SSH, intercambio de claves o algoritmos de clave de host más nuevos que la biblioteca cURL incluida en versiones anteriores del agente no soporta. Los servidores que aún aceptan los algoritmos más antiguos continúan funcionando, razón por la cual la misma clave tiene éxito contra otros hosts y desde la línea de comandos del sistema operativo.
• Resolución: Actualizar el agente privado a la versión 11.37 o posterior, que incluye una biblioteca cURL actualizada con soporte para los cifrados SSH, intercambio de claves y algoritmos de clave de host actuales.

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 el túnel proxy HTTPS por defecto. La propiedad de la JVM jdk.http.auth.tunneling.disabledSchemes bloquea la autenticación básica a menos que se elimine explícitamente.
• Resolución: Agregar -Djdk.http.auth.tunneling.disabledSchemes="" a CATALINA_OPTS antes de iniciar Tomcat. Para instrucciones paso a paso para Windows, Linux y Docker, consulte Permitir autenticación básica durante el túnel proxy HTTPS.

Agentes privados en redes restringidas: Conectividad solo saliente

• Síntoma: Al implementar agentes privados detrás de un firewall corporativo estricto o en un entorno restringido (por ejemplo, OpenShift) junto a un gateway API privado, los equipos de red a veces preguntan qué puertos de entrada deben abrirse en el agente para que Harmony o el gateway puedan alcanzarlo.

• Causa: Los agentes privados no requieren que se abran puertos de entrada, debido a cómo funciona la conectividad del agente:

  • Los agentes privados no aceptan conexiones entrantes de Harmony o de un gateway API privado. El agente establece una conexión WebSocket saliente a Harmony a través de HTTPS (puerto 443). Todo el tráfico de Harmony y del gateway al agente se enruta de regreso a través de esta conexión preestablecida.
  • Un gateway API privado envía solicitudes API a Harmony, y Harmony enruta la solicitud al agente apropiado a través del WebSocket saliente existente. El agente enruta la carga útil de respuesta de la API de regreso al gateway API privado, por lo que el agente también debe poder alcanzar el gateway (directamente o a través de su balanceador de carga en una implementación de múltiples gateways).

• Resolución:

  • Abra HTTPS saliente (puerto 443) desde el host del agente hacia las URL 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 de entrada en el host del agente para Harmony o para el gateway.
  • Al configurar el firewall, incluya en la lista de permitidos los servicios específicos de Jitterbit de la región que se enumeran en Comunicación saliente, la sección que se aplica a un agente privado detrás de un firewall.
  • Si el agente ha sido configurado para usar puertos no predeterminados (personalizados), permita también esos a través del firewall corporativo. Consulte Puertos de red.
  • Si se despliega un gateway API privado, también permita la conectividad saliente desde cada host de agente hacia el gateway (directamente, o a través de su balanceador de carga en un despliegue de múltiples gateways). El agente se conecta al gateway para devolver la carga útil de respuesta de la API. Para el flujo completo de la solicitud, consulte Arquitectura del sistema del gateway API privado.

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

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

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 un estado Pendiente con un ProcessEngine.log que crece rápidamente, cuando el servicio IP Helper falla 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 el 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 (VMs) de Microsoft Azure. Para ajustes generales de rendimiento, consulte 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, reduzca el intervalo de latido:

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

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

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

   #Intervalo de latido del agente (EN MINUTOS)
   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 y E/S

Los errores de WebSocket y E/S se pueden resolver actualizando el tiempo de espera de inactividad de IP de la VM de Azure, el tiempo de espera de inactividad TCP del gateway NAT y el tiempo de espera de flujo de la red virtual (VNET), cada uno a 15 minutos. Esto se cubre en los siguientes pasos.

Identificar errores relevantes

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

Errores en los registros de operación:

La operación "Ejemplo de Operación" se completó con éxito.

No se encontró ningún mensaje al eliminar el mensaje en caché para: Información del Mensaje: AgentId: 000001 AgentGroupId: 000001 MessageId: XXX Versión del Mensaje (Agente): XXXX Versión del Mensaje (Harmony): XXX Contador (Harmony): 1 Marca de Tiempo Enviada (Harmony):2024-01-20 11:55:00.700 , el mensaje se reintentará más tarde OperationInstanceGUID: XXX

El mensaje de ejecución no pudo llegar al agente.

Errores en los registros del agente:

2024-01-20 12:00:00 request handler thread #10642  INFO org.jitterbit.integration.server.api.util.AgentRetryExecutor:53 - Recepción de Mensaje del Agente (OperationInstanceGUID: XXX) falló. Reintentando....
2024-01-20 12:00:00 request handler thread #10642 ERROR org.jitterbit.integration.server.api.util.AgentRetryExecutor:55 - org.springframework.web.client.ResourceAccessException: Error de E/S en la solicitud PUT para "https://na-east.jitterbit.com/jitterbit-cloud-restful-service/agent/ackmsgreceipt": Tiempo de espera de lectura agotado; excepción anidada es java.net.SocketTimeoutException: Tiempo de espera de lectura agotado

E:2024-01-20 12:00:00 request handler thread #884 ERROR org.jitterbit.integration.server.messaging.agent.listener.AgentMessageListener:231 - No se encontró ningún mensaje al eliminar el mensaje en caché para: Información del Mensaje: AgentId: 000001 AgentGroupId: 000001 MessageId: XXX Versión del Mensaje (Agente): XXXX Versión del Mensaje (Harmony): XXX Contador (Harmony): 1 Marca de Tiempo Enviada (Harmony):2024-01-20 11:55:00.700 , el mensaje se reintentará más tarde OperationInstanceGUID: XXX

Detener el agente por drenaje

Detener por drenaje el agente antes de actualizar cualquier configuración de tiempo de espera. Si hay más de un agente en el grupo afectado, detenga por drenaje todos ellos.

Aislar los recursos del agente

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

Actualizar el tiempo de espera inactivo de la IP

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

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

   

3. Haga clic en Configuración y establezca Tiempo de espera inactivo (minutos) en 15:

   

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

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

2. Haga clic en el elemento de la puerta de enlace NAT asociado con la VM y la IP. La puerta de enlace NAT asociada también se lista en el elemento IP en Descripción general junto a Asociado a.

3. Haga clic en Configuración y establezca Tiempo de espera inactivo TCP (minutos) en 15.

Actualizar el tiempo de espera de flujo de la VNET

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

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

   

3. En Descripción general, haga clic en Configurar junto a Tiempo de espera de flujo:

   

4. Habilite Habilitar tiempo de espera de flujo y establezca Tiempo de espera de flujo (minutos) en 15:

   

5. Haga clic en Guardar.

Reiniciar el agente

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

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

Observabilidad

La observabilidad nativa no muestra datos

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

• Causas posibles:

  • La sección [AgentMetrics] en jitterbit.conf no tiene Enabled=true, lo que impide que el servicio de métricas se ejecute.
  • No se han configurado todos los ajustes requeridos en la sección [AgentCapability] a true.
  • Los servicios del agente no se reiniciaron después de realizar cambios en la configuración.
  • El host del agente no puede alcanzar la nube de Harmony, lo que impide que se envíen métricas.
  • El servicio de métricas está configurado para conectarse a la instancia de PgBouncer empaquetada del agente privado en un puerto diferente al que realmente está utilizando PgBouncer, por lo que el servicio de métricas no puede conectarse a él y las métricas solo se recopilan parcialmente. Esta discrepancia de puertos puede ocurrir después de ciertas instalaciones o actualizaciones del agente.
  • Antes de la versión 12.9 del agente, instalar un agente privado como un usuario no root en Linux no provisionaba PgBouncer, por lo que el servicio nunca se inició y su estado siempre aparece como no saludable.

• Resolución:

  • Verifique que jitterbit.conf contenga todos los ajustes requeridos de las secciones [AgentMetrics] y [AgentCapability]. Consulte el ejemplo de configuración completo en la configuración de observabilidad nativa.
  • Revise metrics.log y metrics_service.log en el directorio de registros del agente en busca de errores. Estos registros registran el estado del servicio de métricas e indican si se están recopilando y enviando métricas.
  • Reinicie los servicios del agente si se realizaron cambios en la configuración.
  • Verifique que el host del agente pueda alcanzar la nube de Harmony. Consulte Agente fuera de línea o inaccesible. Si el agente se conecta a través de un proxy, consulte Métricas del agente faltantes cuando el agente se conecta a través de un proxy HTTP.
  • Si las métricas solo se recopilan parcialmente y los pasos anteriores no lo resuelven, comuníquese con soporte de Jitterbit para verificar que el puerto de conexión del servicio de métricas PgBouncer coincida con el puerto configurado de PgBouncer.
  • Para un nuevo agente privado de Linux que no sea root, use la versión 12.9 o posterior, donde PgBouncer se provisiona correctamente durante la instalación. Actualizar un agente de Linux existente que no sea root a la versión 12.9 o posterior no provisiona PgBouncer de manera retroactiva; el agente debe ser instalado 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 a Harmony con éxito a través de un proxy HTTP configurado, pero la pestaña de 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 a través de 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 a pesar de que el agente se conecta con éxito.
• Resolución:
  1. Confirme que el proxy admite HTTPS. Las métricas del agente se envían a través de 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 puede 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. Contacte al soporte de Jitterbit para configurarlo.

El agente de Datadog no se inicia después de la instalación de Docker

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

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

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

  Luego inicie el agente de Datadog. Tenga en cuenta que en Docker, el agente de 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 se instalaron ConfigArgs

• 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: Otorgar a la cuenta del servicio acceso completo a la carpeta de instalación de Jitterbit y reiniciar los servicios.

Apache/Tomcat: MUERTE APPARENTE DE BLOQUEO

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

  ThreadPoolAsynchronousRunner: APPARENT DEADLOCK
  

  El registro también puede mostrar Una conexión existente fue cerrada forzosamente por el host remoto para la base de datos PostgreSQL del agente. Reiniciar el agente restaura temporalmente la operación normal, después de lo cual el bloqueo recurre bajo carga.

• Causas posibles:

  • El grupo de conexiones de la base de datos del agente se bloquea cuando la base de datos interna de PostgreSQL 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 pierde brevemente una conexión de base de datos, por ejemplo, durante una interrupción transitoria de la red, aunque PostgreSQL en sí mismo permanezca saludable y receptivo con los tiempos de espera predeterminados.
  • Procesos obsoletos de Jitterbit están reteniendo hilos y conexiones de base de datos. Esto puede ocurrir cuando se actualiza un agente mientras las operaciones aún están en ejecución, o cuando se detienen los servicios sin que todos los procesos de Jitterbit terminen correctamente.
  • El host del agente está sobrecargado por actividad máxima, o su CPU está siendo estrangulada. Por ejemplo, una instancia de nube con capacidad de ráfaga (como un tipo t3 de AWS) estrangula su CPU una vez que se agotan sus créditos de ráfaga, lo que puede privar a PostgreSQL interno bajo carga.

• Resolución:

  • Detener todos los servicios de Jitterbit, finalizar cualquier proceso de Jitterbit que aún esté en ejecución y luego reiniciar los servicios para despejar el bloqueo.
  • Si el bloqueo está en el grupo de conexiones Java (c3p0) y PostgreSQL está funcionando correctamente, cambiar el agente a su grupo de conexiones interno en C++ configurando UseInternalPooling=true en la sección [DbInfo] de jitterbit.conf, luego reiniciar el agente. El grupo interno se recupera de conexiones caídas o obsoletas de manera más confiable. En instalaciones nuevas de agentes privados de Windows versión 12.5 y posteriores, esto ya está habilitado por defecto.
  • Reducir la carga en el agente: programar operaciones para evitar picos de actividad, agregar agentes al grupo de agentes para balanceo de carga y confirmar que el host cumpla con los requisitos del sistema. Para hosts en la nube, utilizar un tipo de instancia con rendimiento de CPU sostenido (no explosivo).
  • Antes de actualizar un agente, detener el drenaje y permitir que las operaciones en ejecución finalicen, para que no queden procesos sosteniendo conexiones a la base de datos durante la actualización. En entornos ocupados, permitir tiempo adicional para que se complete el drenaje.

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 informa 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.
  

• Causas posibles:

  • Un proceso del agente está manteniendo el archivo abierto. En Windows, el servicio de limpieza no puede eliminar un archivo que está en uso, y Tomcat mantiene sus archivos de registro stdout y stderr abiertos mientras se ejecuta.
  • Un software de terceros (antivirus o un agente de monitoreo) está manteniendo un bloqueo en los archivos del directorio de registros 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 ya no se utilicen. Reinicia el agente después de editar el archivo.
  • Excluye los registros stdout y stderr de Tomcat que se escriben continuamente de las reglas de limpieza, para que el servicio no intente repetidamente archivos que permanecen bloqueados mientras el agente se ejecuta.
  • Si se involucra software de terceros, 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 a soporte de Jitterbit.

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

• Síntoma: Después de reiniciar un host privado de Linux, los servicios del agente no inician. Ejecutar sudo jitterbit status muestra que el programador y otros servicios no están en funcionamiento, 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 empaquetado son demasiado permisivos. PostgreSQL requiere que el directorio de datos sea 700 (solo para el propietario). Si los permisos son más laxos (por ejemplo, 755 o 777), PostgreSQL se niega a iniciar, lo que impide que el resto del agente inicie.

• Resolución:

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

     sudo chown -R jitterbit:jitterbit /opt/jitterbit
     

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

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

  3. Inicia los servicios del agente:

     sudo /etc/init.d/jitterbit start
     

Linux: El antivirus elimina PgBouncer, el agente no puede autenticarse en la base de datos empaquetada

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

  [FATAL] password authentication failed for user "jitterbit"
  

  El registro del agente muestra que no puede conectarse a la base de datos. La falla persiste a través de una desinstalación y reinstalación completas.

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

• Resolución:

  1. Desactivar temporalmente el antivirus o el producto de protección de endpoints en el host del agente.
  2. Agregar el directorio de instalación de Jitterbit (típicamente /opt/jitterbit) a la lista de exclusiones 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 volver a habilitar 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 al final de su vida útil.
• 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 soportado 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.

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

El agente no se reinicia 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) no se reinicia después de ser detenido. Esto se aplica a los agentes de Docker que utilizan un volumen persistente para /opt/jitterbit/Resources, y a los agentes de Linux no contenedorizados.

• 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 reiniciarse, el agente intenta usar las credenciales obsoletas y no logra autenticarse.

  Nota

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

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

  En un agente de Linux no contenedorizado, elimina el archivo directamente:

  rm /opt/jitterbit/Resources/credentials.txt
  

  En un agente de 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
  

  Reemplace VOLUME_NAME con el nombre del volumen de Docker bajo el cual se monta /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.
  

• Causas posibles:

  • Demasiados pocos agentes en el grupo de agentes están en ejecución y unidos al clúster. Para un grupo de \(N\) agentes, contados independientemente de si cada agente está en ejecución, \((N / 2) + 1\) agentes (redondeado hacia abajo) deben estar en ejecución y ser parte del clúster.
  • Uno o más agentes perdieron su conexión con el clúster y no pudieron volver a unirse, reduciendo el número de agentes en ejecución y unidos por debajo del requerido \((N / 2) + 1\).
  • 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 requerido \((N / 2) + 1\) de 3, por lo que ambos informan el error a pesar de que cada agente está en ejecución.

• Resolución:

  • Confirme que \((N / 2) + 1\) de los agentes en el grupo están en ejecución y son parte del clúster, donde \(N\) es el número de agentes registrados en el grupo de agentes, independientemente de si cada uno está en ejecución. 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, utilice la API REST del Servicio de escucha para mostrar el estado del clúster.
  • Verifique 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, restaure el clúster manualmente. Consulte Restauración del clúster después de la 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 al grupo dividido en dos mitades, ninguna de las cuales es lo suficientemente grande como para mantener el clúster en funcionamiento.

Mensajes del servicio de escucha no entregados

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

Registro

Los registros de operaciones de API personalizados 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 o en la página Runtime de la Consola de Administración.
• Causa: Cuando una API personalizada activa una operación, los registros de la operación se generan solo cuando la operación no tiene éxito. Las operaciones de API personalizadas exitosas no producen ninguna entrada de registro por defecto.
• Resolución: Para capturar registros de operaciones de API personalizadas exitosas, habilite el registro de depuración de operaciones para la operación. Tenga en cuenta que API Manager tiene su propia vista de registro separada para las solicitudes de API.

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

• Síntoma: Se habilitó el registro de depuración de operaciones 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 operaciones es poco confiable. Los registros pueden dejar de generarse antes de que finalice el período de tiempo configurado.
• Resolución: Vuelva a habilitar el registro de depuración de operaciones según sea necesario.

Archivos de registro de depuración de operaciones faltantes datos .input o .output

• Síntoma: En un agente privado, se ha habilitado el registro de depuración de operaciones con datos de entrada y salida de componentes 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 correspondientes .input y .output.

• Causas posibles:

  • El servicio de limpieza del agente está eliminando archivos .input y .output antes de que puedan ser revisados.
  • El agente se reinició mientras la operación aún estaba en ejecución, por lo que los archivos nunca se escribieron completamente. Consulte Datos de entrada/salida de componentes no generados para ese escenario.

• Resolución:

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

  2. Encuentre la regla de limpieza para el directorio DataInterchange/Temp/Debug y aumente el valor de <FileAge NumDays = "2"...> a un período de retención más largo (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. Reinicie los servicios del agente.

Datos de entrada/salida de componentes no generados

• Síntoma: Se habilitó el registro de depuración de operaciones con la generación de datos de entrada y salida de componentes activada, pero no aparecen archivos de datos de entrada/salida para operaciones de agentes privados.

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

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

Si el registro muestra errores, reinicie el servicio de Verbose Log Shipper. En Linux, esto se puede hacer sin reiniciar todo el agente:

jitterbit stop verboselogshipper
jitterbit start verboselogshipper

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