Solução de problemas do agente privado Jitterbit

Esta página fornece orientações para solução de problemas comuns encontrados ao instalar, executar ou gerenciar um agente privado Jitterbit. Comece com os passos de diagnóstico abaixo e, em seguida, encontre seu erro específico na seção relevante. Entre em contato com o suporte Jitterbit para problemas não listados aqui.

Para uma referência unificada que abrange integração, automação, gerenciamento de API, EDI e desenvolvimento de aplicativos em um só lugar, consulte o guia de solução de problemas do Harmony.

Passos de Diagnóstico

Esses passos são o ponto de partida recomendado para a maioria dos problemas com agentes privados.

Verificar o status do agente

Revise o status atual do agente no Console de Gerenciamento em Agentes > Privado, e use isso para restringir o problema. Para as definições completas de status e como elas transitam, veja Status do agente.

Verifique os arquivos de log do agente

Os arquivos de log do agente são a principal fonte de informações de diagnóstico. Verifique o seguinte arquivo em busca de erros relacionados à conectividade, saúde do serviço e falhas de operação:

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

Para uma lista completa de arquivos de log disponíveis, consulte Logs do agente.

Use as Ferramentas de Suporte do Agente

As Ferramentas de Suporte do Agente fornecem comandos de diagnóstico que são executados diretamente no host do agente:

• connection-check: Verifica a conectividade do agente com a nuvem Harmony, serviços Apache e Tomcat.
• service-status: Mostra o estado de execução de todos os serviços do agente (Apache, Tomcat, PostgreSQL, PgBouncer, VerboseLogShipper).
• generate-report: Cria um relatório HTML de diagnóstico e um arquivo ZIP de todos os arquivos de log do agente, útil ao escalar para o suporte da Jitterbit. Em agentes Linux, o relatório atualmente omite dados do PostgreSQL; agentes Windows não são afetados.

Para acessar as ferramentas:

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

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

Reinicie o agente

Muitos problemas transitórios (caches de roteamento obsoletos, exaustão de pool, condições de bloqueio) são resolvidos com uma reinicialização do serviço:

• Windows: Inicie ou reinicie o agente
• Linux: Inicie ou reinicie o agente

Status do agente e conectividade

Agente offline ou inacessível

• Sintoma: A aba Privada da página Agentes do Console de Gerenciamento mostra o agente como Desconhecido ou Parado, ou o Studio exibe um erro Agente Não Está Executando ou Inacessível.

• Causas possíveis:

  • Os serviços da Jitterbit não estão em execução.
  • Os serviços estão em execução, mas o host do agente não consegue acessar a nuvem Harmony.
  • Um proxy corporativo está impedindo a conexão do agente.

• Resolução:

  • Se os serviços do Jitterbit não estiverem em execução, inicie-os:

    • Windows: Veja Iniciar um agente do Windows.
    • Linux: Veja Iniciar um agente do Linux.

    Se o serviço falhar ao iniciar, verifique o seguinte em busca de mensagens de erro:

    • Windows: C:\Program Files (x86)\Jitterbit Agent\log e o log de Aplicativos do Visualizador de Eventos do Windows.
    • Linux: /opt/jitterbit/log.

    A conta que executa os serviços do Jitterbit requer direitos de administrador local no Windows e acesso total ao diretório de instalação do Jitterbit.

  • Se os serviços estiverem em execução, mas não conseguirem acessar a nuvem Harmony, verifique o seguinte:

    • A conectividade com a Internet do host do agente está funcionando.
    • O log do agente (jitterbit-agent.log) não contém mensagens de erro sobre conectividade com a nuvem.
    • O agente pode acessar o portal Harmony na porta 443.

  • Se o agente se conectar através de um proxy corporativo, verifique se o proxy está configurado corretamente para o agente, incluindo o domínio NTLM se o proxy usar autenticação NTLM. Veja Servidor proxy para agentes privados do Jitterbit. O log de negação do servidor proxy é útil para diagnosticar o que o proxy está bloqueando.

  • Se os serviços do agente estiverem saudáveis no host (jitterbit status mostra todos os serviços em execução), mas o agente alternar repetidamente para Desconhecido, ou ciclar entre Executando, Desconhecido e Parado, a conexão ou o processo do agente provavelmente está sendo interrompido entre os batimentos cardíacos. Verifique as seguintes causas possíveis:

    • Um dispositivo de rede (firewall, gateway NAT ou tempo limite de inatividade de VM na nuvem) pode estar fechando a conexão de saída do agente entre os batimentos cardíacos. Tente reduzir o intervalo de batimento cardíaco do agente (agent.heart.beat.interval). Para agentes hospedados na nuvem, veja Azure VM: Conexões perdidas e erros de WebSocket/I/O, que também se aplica a outras redes restritas, como AWS.
    • O agente pode ter travado sob pressão de memória. Verifique se há arquivos de despejo de falha OutOfMemoryError ou hs_err_pid. Veja Espaço de heap do Java: OutOfMemoryError.
    • Se os agentes foram recentemente migrados para um novo sistema operacional enquanto reutilizavam um grupo de agentes que anteriormente hospedava agentes no antigo SO, o grupo reutilizado pode ser a causa. Veja Agente mostra Desconhecido ou Parado após reutilizar um grupo de agentes entre sistemas operacionais.

Agente mostrando versões ou endereços IP diferentes

• Sintoma: A aba Privada da página Agentes do Console de Gerenciamento exibe versões ou endereços IP diferentes para um agente privado, ou os valores alternam após reiniciar os serviços.
• Possível causa: A máquina host do agente pode ter sido duplicada em nível de infraestrutura (por exemplo, um clone de VM, imagem de disco, modelo de máquina ou snapshot criado após o agente ter sido instalado e registrado). O host duplicado carrega as mesmas credentials.txt do agente, então ambos os hosts se autenticam no Harmony como o mesmo agente e operam em paralelo, colidindo. Dois agentes não podem ser executados simultaneamente sob as mesmas credenciais.
• Resolução:
  1. Confirme se uma duplicata está em execução. Pare o agente na máquina host que você pretende manter, aguarde 10 minutos e, em seguida, atualize a aba Privada da página Agentes do Console de Gerenciamento. Se o agente mudar de Parado para Em Execução, outro host está reportando sob a mesma identidade.
  2. Identifique e desligue o host duplicado.
  3. Se a duplicata não puder ser desligada, desinstale o agente, crie um novo agente com um nome diferente e reinstale-o na máquina host que você deseja manter.
  4. Verifique se o novo agente está listado como Em Execução na aba Privada da página Agentes do Console de Gerenciamento.
  5. Exclua a entrada do agente antigo usando Ações > Remover.

Agente mostra Desconhecido ou Parado após reutilizar um grupo de agentes entre sistemas operacionais

• Sintoma: Após migrar agentes privados para um sistema operacional diferente (por exemplo, de Windows para Linux) enquanto reutiliza o mesmo grupo de agentes, os agentes migrados intermitentemente aparecem como Desconhecido ou Parado na aba Privada da página Agentes do Console de Gerenciamento, mesmo que jitterbit status mostre os serviços em execução e as operações ocorram normalmente.
• Possível causa: Reutilizar um grupo de agentes do sistema operacional anterior pode deixar para trás metadados que interferem na comunicação de status para os novos agentes. O efeito é tipicamente cosmético: os serviços e operações continuam a funcionar normalmente.
• Resolução: Crie um novo grupo de agentes limpo para os agentes migrados em vez de reutilizar o grupo do sistema operacional anterior e, em seguida, registre os agentes lá.

Falha na sincronização do agente: alterações no projeto não aplicadas

• Sintoma: Após implantar alterações no Studio, o agente continua executando a versão anterior do projeto, ou uma operação falha porque uma conexão recém-adicionada não é encontrada no agente.

• Causas possíveis:

  • A implantação utilizou Implantação Configurável, que implanta apenas os fluxos de trabalho e operações selecionados. Qualquer parte do projeto fora dessa seleção permanece na versão previamente implantada no agente.
  • O componente não é utilizado no fluxo lógico de um fluxo de trabalho implantado. Componentes não utilizados não são implantados, portanto, uma conexão que nenhuma operação implantada referencia não é enviada ao agente.
  • Um tempo limite de rede ou erro de autorização ocorreu durante a sincronização.
  • O espaço em disco baixo no host do agente impediu que os arquivos do projeto sincronizado fossem gravados.

• Resolução:

  • Reimplantar o projeto completo: no Studio, use Implantar, que implanta todas as operações do projeto, em vez de uma Implantação Configurável de apenas fluxos de trabalho ou operações selecionados.
  • Reinicie os serviços do agente para forçar uma nova sincronização de todos os projetos implantados.
  • Revise os logs do agente em busca de tempos limite de rede ou erros de autorização relacionados à sincronização.
  • Verifique o espaço em disco disponível no host do agente. Um disco cheio ou quase cheio pode impedir que o agente grave arquivos de projeto sincronizados. Veja Espaço em disco e acúmulo de logs.

Operações atrasadas ou enfileiradas após a implantação do projeto

• Sintoma: Após implantar um projeto no Studio, operações acionadas não começam imediatamente, ou um breve acúmulo de operações enfileiradas aparece.
• Causa: O ambiente está bloqueado enquanto o agente sincroniza o projeto implantado. Nenhuma operação pode ser executada durante essa janela.
• Resolução:
  1. Para medir quanto tempo os bloqueios de sincronização estão durando, escaneie jitterbit-agent.log em busca de environment-deploy. Cada entrada de log inclui o ID do ambiente e a duração da sincronização em milissegundos.
  2. Tempos de sincronização consistentemente longos indicam um projeto grande ou conectividade lenta com o Harmony. Para reduzir os tempos de sincronização, veja ajuste de desempenho de sincronização do ambiente.
  3. Se as durações de sincronização forem consistentemente excessivas (mais de alguns minutos), entre em contato com o suporte da Jitterbit.

Agente mostrando-se incapaz

• Sintoma: Operações enviadas ao grupo de agentes estão sendo reprocessadas ou atrasadas em vez de serem executadas imediatamente. ProcessEngine.log contém mensagens repetidas como:

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

  Capability status changed from true to false
  

• Possíveis causas:

  • Cada thread de trabalho no mecanismo de processo do agente já está em uso, portanto, o agente não pode aceitar outra operação até que uma thread seja liberada. O tamanho do pool é definido por MaxNumberOfWorkerThreads na seção [ProcessEngine] do jitterbit.conf.
  • Uma métrica de capacidade opcional está habilitada e atingiu seu limite. O uso de CPU, uso de memória e uso de threads do Apache podem contribuir para o status de capacidade, mas todos os três estão desativados por padrão e se aplicam apenas quando ativados na seção [AgentCapability] do jitterbit.conf. O uso de memória é coletado apenas em agentes Windows, portanto, não contribui para o status de capacidade em um agente Linux, mesmo quando as configurações de memória estão habilitadas. O Apache atende apenas a solicitações de API, portanto, o uso de threads do Apache é relevante apenas em um agente que lida com APIs.
  • Um único agente no grupo está lidando com mais carga do que pode suportar, enquanto outros agentes no grupo estão ociosos ou subutilizados.

• Resolução: Revise ProcessEngine.log em busca de longas sequências de alterações no status de capacidade para confirmar que o agente está alternando entre estados incapazes, e então investigue o seguinte:

  • Se muitas operações estão sendo executadas simultaneamente, revise MaxNumberOfWorkerThreads na seção [ProcessEngine] do jitterbit.conf. Aumentar esse valor permite mais operações simultâneas, mas também aumenta a demanda de CPU e memória, portanto, defina-o de forma conservadora.
  • Determine quais métricas de capacidade estão habilitadas na seção [AgentCapability]. Se nenhuma estiver habilitada, a carga de CPU e memória não é o que alterou o status de capacidade do agente, e a disponibilidade de threads é o gatilho mais provável. Se o uso de CPU ou memória estiver habilitado, verifique-o antes das métricas de thread: qualquer um que ultrapasse seu limite torna o agente incapaz, independentemente da disponibilidade de threads. Em um agente Linux, o uso de CPU é a única métrica de recurso do sistema que se aplica.
  • Verifique o uso de CPU e memória no host do agente no momento do problema. Se a observabilidade nativa estiver habilitada, revise os gráficos de Capacidade de Recursos do Sistema, Threads do Apache e Threads do Tomcat na aba Métricas da página Agentes do Console de Gerenciamento. Ao revisar gráficos para um grupo de múltiplos agentes, use valores de pico ou máximos em vez de médias, pois as médias podem mascarar um único agente sobrecarregado enquanto o restante do grupo parece saudável.
  • Se o grupo de agentes contiver múltiplos agentes, verifique ProcessEngine.log em todos os agentes do grupo para determinar se todos os agentes estavam incapazes simultaneamente quando a operação falhou. Se apenas um agente estava incapaz, a operação deveria ter sido direcionada a um agente capaz. Verifique se o balanceamento de carga está configurado corretamente para o grupo.
  • Se os limites de recursos estão sendo constantemente atingidos, adicione agentes ao grupo para distribuir a carga.
  • Se a pressão de memória for o gatilho, veja Espaço de heap Java: OutOfMemoryError.

Falhas de transformação: "Falha ao encontrar arquivo no armazenamento local de arquivos"

• Sintoma: Uma operação falha durante uma transformação com um erro indicando que um arquivo está faltando no armazenamento local de arquivos do 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 possível: Os metadados de implantação de um arquivo não foram totalmente sincronizados do cloud Harmony para o agente, então o agente não consegue localizar o arquivo em tempo de execução. Isso geralmente é transitório (por exemplo, uma breve interrupção de sincronização), mas também pode ocorrer após a exportação e reimportação de um projeto entre ambientes.

• Resolução:
  1. Execute novamente a operação. Na versão do agente 11.38 e posteriores, o agente se autocorrige nessa condição: o erro ocorre no máximo uma vez por ID de arquivo em um determinado agente, e o agente restaura os metadados ausentes na próxima sincronização do ambiente (na próxima execução da operação ou implantação). Na maioria dos casos, executar a operação novamente resolve o problema.
  2. Se o mesmo arquivo continuar falhando em várias execuções em um agente atual, é provável que haja um problema mais profundo, como um ambiente que atingiu seu limite de registros de implantação ou uma regressão específica de versão. Entre em contato com o suporte Jitterbit com o nome da operação que falhou e os TransformID e File_ID do erro.

Erros de instalação e atualização

Erro 1720 ou 1722 na instalação do Windows

• Sintoma: A instalação do agente privado do Windows falha durante o processo, com um desses erros do Instalador do 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 os erros significam que uma etapa no instalador (uma ação personalizada, nomeada na mensagem de erro 1722) não foi concluída. Na maioria das vezes, a etapa que falha é a configuração do PostgreSQL incluído no instalador, caso em que o log do instalador também pode mostrar um erro de script KoGetDbService ou KoInstallPostgreSQLNew, ou [Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified, e o banco de dados PostgreSQL incluído e o serviço do Windows jitterbitpostgres podem não ser totalmente criados. A mensagem pode, em vez disso, nomear uma ação diferente, como InstallVerboseLogShipper.

• Causas possíveis:

  • Um Microsoft Visual C++ Redistributable ausente ou em conflito (o PostgreSQL incluído requer isso).
  • Caracteres proibidos na senha do PostgreSQL.
  • Em uma reinstalação, componentes remanescentes do PostgreSQL de um agente anterior. O desinstalador do agente não remove o PostgreSQL, o usuário do Windows jitterbitpostgres ou suas entradas de registro por design, e esses remanescentes podem impedir que a nova configuração do PostgreSQL seja concluída (por exemplo, a conta de serviço jitterbitpostgres não pode ser recriada).
  • Em uma reinstalação ou atualização, componentes remanescentes do serviço de envio de logs detalhados de um agente anterior. Assim como com o PostgreSQL, uma desinstalação padrão não remove o serviço de envio de logs detalhados ou seus arquivos, e esses remanescentes podem causar a falha da ação InstallVerboseLogShipper do instalador.

• Solução:

  • Instale o Microsoft Visual C++ Redistributable de 64 bits para Visual Studio usando vc_redist.x64.exe (cobre o Visual Studio 2015, 2017 e 2019) antes de instalar o agente, e mantenha-o instalado, pois removê-lo durante uma limpeza também quebra a instalação.

  • Se a senha do PostgreSQL contiver caracteres proibidos, mude a senha para uma válida antes de tentar a instalação novamente.

    Nota

    Nos agentes privados 12.8 e posteriores, o instalador valida a senha da conta de serviço do PostgreSQL (jitterbitpostgres) em relação às restrições de caracteres no momento da entrada e solicita que você a corrija antes que o PostgreSQL seja instalado.

  • Se você estiver reinstalando após um agente anterior, remova completamente o PostgreSQL restante primeiro: siga Desinstalar um agente privado do Windows, depois confirme que o usuário do Windows jitterbitpostgres, os diretórios do programa e dos dados do PostgreSQL e as chaves de registro do PostgreSQL foram removidos.

  • Se a mensagem de erro 1722 mencionar a ação InstallVerboseLogShipper, remova o serviço de envio de log detalhado restante e seus arquivos do agente anterior, depois desinstale o agente novamente e reinstale.

    Se a instalação ainda falhar após uma limpeza completa, entre em contato com o suporte da Jitterbit.

Serviço PostgreSQL removido após falha na atualização no Windows

• Sintoma: Após uma falha na atualização do agente privado no Windows, o serviço PostgreSQL (postgresql-x64-<VERSION>) não aparece mais nos Serviços do Windows, e os serviços do agente Jitterbit falham ao iniciar devido a uma dependência ausente.

• Causa: Isso ocorre com versões de agentes privados anteriores a 11.59 / 12.3 quando uma senha incorreta é inserida durante a atualização e o instalador falha ao reverter corretamente. Este problema é resolvido nos agentes privados 11.59 / 12.3 e posteriores, onde uma senha incorreta bloqueia a atualização na mesma caixa de diálogo e permite a reentrada ou cancelamento sem afetar a instalação existente.

• Resolução:

  1. Abra um prompt de comando como administrador.

  2. Re-registre o serviço PostgreSQL:

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

     Substitua <VERSION> pelo número da versão do PostgreSQL. Para encontrá-lo, consulte versão do PostgreSQL incluída com o agente privado.

  3. Inicie os serviços do PostgreSQL e PgBouncer:

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

  4. Inicie todos os serviços do agente Jitterbit:

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

  5. Uma vez que o agente esteja em execução, reinicie as senhas do administrador do PostgreSQL e da conta de serviço antes de tentar a atualização novamente.

TFA impede a instalação do agente Windows de 64 bits

• Sintoma: A instalação de um agente privado Windows de 64 bits falha quando a autenticação de dois fatores (TFA) está ativada na organização.
• Resolução: Desative temporariamente a TFA, instale o agente e, em seguida, reative a TFA. A configuração Exigir autenticação de dois fatores (TFA) está na aba Gerenciamento de Usuários das políticas de uma organização, acessada a partir da página Organizações do Console de Gerenciamento.

Recuperar uma instalação do Windows que falhou

• Sintoma: A instalação ou atualização de um agente privado Windows falha ou deixa o agente em um estado quebrado.
• Resolução: Desinstale completamente o agente e, em seguida, reinstale o software do agente.

A instalação não-root do Linux falha

• Sintoma: O instalador Linux Redhat Non-Root (x64) falha.
• Resolução: Verifique o seguinte:
  • O usuário não-root tem privilégios sudo. Um administrador do sistema deve adicionar o usuário ao grupo wheel. Para verificar a associação atual ao grupo, execute groups.
  • Ao fazer login como usuário jitterbit, a variável de ambiente JITTERBIT_HOME está definida para o local de instalação:

echo $JITTERBIT_HOME

O resultado deve ser /opt/jitterbit. Isso é configurado por $HOME/.bashrc.d/jitterbit quando as instruções de instalação são seguidas. Para configurá-lo manualmente, execute:

. /opt/jitterbit/scripts/set.env

• Se o instalador falhar com um erro OPENSSL_3.4.0, este é um problema conhecido no RHEL 9.7 e versões posteriores. Veja A instalação de agente privado não-root no RHEL 9.7 e versões posteriores apresenta um erro OpenSSL nas questões conhecidas do agente privado para uma solução alternativa.

Driver JDBC: "Nenhum driver adequado encontrado"

• Sintoma: Uma conexão com o banco de dados falha porque o driver JDBC necessário não está instalado no agente, com um erro como Nenhum driver adequado encontrado para jdbc:<subprotocol>://....
• Causa: O Jitterbit não é fornecido com todos os drivers JDBC. O driver necessário deve ser instalado manualmente.
• Resolução: Instale o driver necessário manualmente: registre-o em JdbcDrivers.conf e copie o driver .jar para JITTERBIT_HOME/tomcat/drivers/lib/, em seguida, reinicie o agente. Para os passos completos, veja Instalar um driver JDBC.

Conector não baixado para o agente

• Sintoma: As operações falham com erros indicando que um conector está indisponível ou não encontrado no agente, tipicamente após uma nova versão do conector ser lançada ou após implantar um projeto que usa um conector baseado no SDK do 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
  

• Possíveis causas:

  • A versão do conector necessária pelo projeto ainda não foi baixada da nuvem para o agente. Isso é frequentemente transitório e se resolve dentro de alguns minutos.
  • Para agentes privados: o agente não consegue acessar a nuvem Harmony para baixar o conector.

• Resolução:

  • No Studio, abra a conexão afetada e clique em Testar. Isso faz com que o agente baixe a versão mais recente do conector da nuvem.
  • Se o conector ainda não for baixado, verifique se a política organizacional Desativar Atualização Automática de Conectores está habilitada. Quando está habilitada, o botão Testar não baixa versões de conectores. Veja Gerenciamento de Agentes.
  • Para baixar o conector sem alterar a política, vá para a página Agentes do Console de Gerenciamento, selecione o grupo de agentes e escolha Ação > Atualizar conectores. Isso força uma atualização de conector em todo o grupo e não é afetado pela política Desativar Atualização Automática de Conectores.
  • Para agentes privados, verifique se o host do agente consegue acessar a nuvem Harmony. Veja Agente offline ou inacessível.

A instalação do agente não pode ser registrada através de um proxy corporativo

• Sintoma: A instalação de um agente privado em um host atrás de um proxy corporativo falha durante a etapa de registro inicial, e o instalador informa que não conseguiu acessar a nuvem Harmony:

  Could not connect to Jitterbit Harmony cloud
  

• Causas possíveis:

  • O proxy está bloqueando a conexão do agente com a nuvem Harmony durante o registro.
  • O proxy requer autenticação que a configuração de proxy do agente não fornece. Agentes privados suportam autenticação de proxy, incluindo um domínio NTLM. Veja Servidor proxy para agentes privados Jitterbit.

• Resolução:

  1. Configure o proxy durante a configuração do agente para que o instalador possa acessar a nuvem Harmony através dele, fornecendo as credenciais do proxy (e o domínio NTLM, se o proxy exigir). Veja Configurar um proxy durante a configuração do agente.
  2. Se o registro ainda falhar através do proxy, peça à sua equipe de rede para permitir os domínios e endereços IP do Jitterbit através do proxy, ou contornar o proxy para eles. As URLs específicas da região do Harmony estão documentadas em Informações da lista de permissão.
  3. Execute o instalador novamente assim que o proxy estiver configurado ou o host puder acessar a nuvem Harmony.

Problemas de desempenho e recursos

Espaço de heap Java: OutOfMemoryError

• Sintoma: Operações que processam arquivos grandes ou executam muitas operações simultaneamente falham com:

  java.lang.OutOfMemoryError: Java heap space
  

• Causa: O tamanho máximo do heap Java do agente privado (-Xmx) é muito pequeno para a carga de trabalho (arquivos grandes ou alta concorrência de jobs).

• Resolução:
  1. Aumente o tamanho máximo do heap Java do agente privado. Veja Memória heap do Tomcat para saber como alterar o valor de -Xmx (por exemplo, de -Xmx1024m para -Xmx4096m).
  2. Reinicie os serviços do agente após fazer a alteração.
  3. Para operações que processam arquivos grandes, configure divisão para reduzir o uso de memória por job. O Studio aplica transformações de streaming automaticamente onde elas se qualificam.
  4. Se a observabilidade nativa estiver habilitada, use o gráfico Capacidade de Recursos do Sistema na aba Métricas da página Agentes do Console de Gerenciamento para monitorar o uso de memória ao longo do tempo e dimensionar corretamente o heap para a carga de trabalho.

Espaço em disco e acumulação de logs

• Sintoma: O host do agente privado fica sem espaço em disco, o que pode causar a parada do PostgreSQL ou falhas nas operações com erros de permissão. Arquivos de log e temporários se acumulam nos diretórios do agente, especialmente em agentes que processam altos volumes.
• Resolução:
  • Verifique o espaço em disco disponível no host do agente.
  • Identifique arquivos grandes. Os logs do agente e arquivos temporários estão em JITTERBIT_HOME/log, JITTERBIT_HOME/tomcat/logs (catalina.out) e JITTERBIT_HOME/DataInterchange/Temp. Veja Arquivos de log para a lista completa. Um único arquivo de log pode crescer para muitos gigabytes quando um componente registra excessivamente (por exemplo, um conector verboso inundando catalina.out) ou quando um erro se repete (por exemplo, uma conexão de banco de dados falhada se repetindo em ProcessEngine.log). Limpe arquivos excessivamente grandes se o espaço estiver criticamente baixo; limpar o arquivo e reiniciar o agente também pode parar o erro subjacente.
  • Confirme se o serviço de limpeza está em execução e se sua retenção está sendo respeitada. Na seção [FileCleanup] do jitterbit.conf, verifique se AutoStart está como true e revise FrequencyInHours. A retenção por diretório é definida em CleanupRules.xml usando NumDays ou NumOfHours.
  • Se o serviço de limpeza não puder excluir arquivos de log ativos (o Tomcat mantém seus logs stdout e stderr abertos no Windows), aumente o FileAge para aquele diretório em CleanupRules.xml para pelo menos um dia, para que a limpeza não tenha como alvo arquivos que ainda estão sendo gravados.
  • Se grandes arquivos de despejo de falhas .dmp estiverem consumindo o disco, veja Arquivos de mini-despejo do JVM preenchem o disco do agente.

Loop de reinicialização do serviço do agente

• Sintoma: Os serviços do agente falham e reiniciam repetidamente. O Tomcat ou o Process Engine para e inicia em um loop sem permanecer online, e as operações falham com erros como O serviço Tomcat não está em execução. Se jitterbit status mostrar todos os serviços saudáveis no host, mas o status exibido apenas oscila entre Executando, Desconhecido e Parado, isso é um problema de conectividade em vez de um loop de falhas. Veja Agente offline ou inacessível.

• Causas possíveis:

  • Um processo Jitterbit órfão de uma execução anterior (um processo Tomcat, Process Engine ou scheduler) ainda está ocupando a porta do serviço, então cada reinicialização falha com java.net.BindException: Endereço já em uso e o agente entra em ciclo.
  • O host fica sem memória e o sistema operacional termina o processo. Isso pode acontecer quando o host tem memória insuficiente para a carga de trabalho ou quando o limite de memória de um contêiner está definido muito baixo.
  • O host do agente está com pouco espaço em disco, ou o banco de dados interno do PostgreSQL cresceu o suficiente para falhar na inicialização.
  • O Process Engine está falhando repetidamente sob carga sustentada.

• Resolução:

  • Confirme se este é um verdadeiro loop de falhas. Verifique os logs do Tomcat em JITTERBIT_HOME/tomcat/logs/ e ProcessEngine.log para a exceção registrada em cada reinício. Um java.net.BindException: Address already in use indica que um processo órfão está ocupando a porta.
  • Pare o agente e finalize quaisquer processos Jitterbit restantes antes de reiniciá-lo. Com o agente parado, verifique por processos perdidos: no Linux, execute ps aux | grep -E 'tomcat|jitterbit' e kill quaisquer IDs de processo restantes; no Windows, finalize quaisquer processos Jitterbit ou Tomcat perdidos no Gerenciador de Tarefas. Inicie o agente novamente assim que não houver mais processos.
  • Verifique eventos de falta de memória. No Windows, revise os logs de Aplicativo e Sistema no Visualizador de Eventos; no Linux, execute journalctl -u jitterbit ou verifique /var/log/syslog para eventos do OOM killer. Se o host estiver ficando sem memória, aumente a memória disponível (ou o limite de memória do contêiner). Veja Espaço de heap Java: OutOfMemoryError.
  • Verifique o espaço em disco e o banco de dados interno. Um disco cheio ou um banco de dados PostgreSQL inchado pode fazer com que os serviços falhem a cada reinício. Veja Espaço em disco e acumulação de logs.
  • Se os logs mostrarem que o Process Engine está falhando em uma operação específica, entre em contato com suporte Jitterbit com os detalhes da operação e os logs do agente.
  • Se a observabilidade nativa estiver habilitada, abra a aba Métricas da página Agentes do Console de Gerenciamento e revise os gráficos de serviço Tomcat e Process Engine para identificar quando os serviços começaram a falhar.

Operações expirando ou ignorando configurações de tempo limite

• Sintoma: Operações são executadas indefinidamente ou por mais tempo do que o esperado. Para operações acionadas por API, as configurações de tempo limite configuradas no Studio parecem não ter efeito, e as operações podem permanecer presas em um status de Executando.

• Causas possíveis:

  • Por padrão, operações acionadas por APIs do API Manager ignoram as configurações de tempo limite de operação do Studio. A configuração EnableAPITimeout em jitterbit.conf deve ser explicitamente habilitada para que as operações de API respeitem os valores de tempo limite.
  • Nenhum tempo máximo de execução da operação está definido, portanto, as operações são executadas sem um limite de tempo rígido.

• Resolução:

  1. Para aplicar as configurações de tempo limite de operação para operações acionadas por API, defina EnableAPITimeout=true na seção [Settings] do jitterbit.conf.
  2. Para limitar o tempo total de execução de qualquer operação, defina MaxOperationRuntimeSeconds na seção [ProcessEngine] do jitterbit.conf. Isso requer que RunOperationsInSeparateProcess seja true (o padrão).
  3. Reinicie os serviços do agente após fazer alterações no jitterbit.conf.

Através do agente inalterado após aumentar max.concurrent.requests

• Sintoma: Após aumentar max.concurrent.requests em jitterbit-agent-config.properties, a capacidade de processamento do agente não melhora.

• Causas possíveis:

  • Apenas max.concurrent.requests foi alterado. A capacidade de processamento do agente também depende dos pools de threads do Tomcat e Apache e dos pools de conexão HTTP, portanto, aumentar essa única configuração sem escalar as outras em conjunto não produz ganho.
  • O host do agente não possui CPU ou memória suficientes para a concorrência adicional, ou o agente está entrando em um estado incapaz sob carga.

• Resolução:

  • Siga o procedimento completo de ajuste em vez de alterar apenas max.concurrent.requests, escalando as configurações relacionadas ao pool de threads e ao pool de conexões em conjunto. Veja Desempenho e ajuste do agente.
  • Confirme que o host do agente possui CPU e memória adequadas para a maior concorrência. Se o agente travar ou entrar em um estado incapaz sob carga, veja Loop de reinício do serviço do agente e Espaço de heap Java: OutOfMemoryError.

Atraso na transformação XML após a atualização para o agente 11.45 ou posterior

• Sintoma: Após atualizar um agente privado para a versão 11.45 ou posterior, uma transformação que itera sobre um grande array leva mais tempo para ser executada do que na versão 11.44. A lentidão é específica para caminhos de mapeamento que usam a notação # para iterar sobre cada elemento de um grande array (aproximadamente várias centenas a alguns milhares de registros). Transformações que não iteram sobre grandes arrays não são afetadas.
• Causa possível: A biblioteca de análise XML usada pelo agente foi atualizada na versão 11.45, e a versão atualizada analisa grandes dados XML mais lentamente. Isso afeta transformações que iteram sobre um grande array, porque o mapeamento percorre repetidamente os dados analisados.
• Resolução:
  • Revise os caminhos de mapeamento da transformação para a notação #. Se um caminho usar # para iterar sobre um array, mas apenas o primeiro elemento for necessário, remova o # e reimplante. Remover o # mapeia apenas o primeiro elemento, portanto, aplique isso apenas onde a iteração sobre o array completo não é necessária.
  • Se o mapeamento precisar iterar sobre o array completo, processe menos registros por execução dividindo um grande conjunto de dados em lotes menores, para que cada transformação percorra um array menor.

Arquivos de mini-dump da JVM preenchem o disco do agente

• Sintoma: O agente gera continuamente grandes arquivos de falha da JVM (.dmp e .mdmp mini-dumps, e arquivos hs_err_pid*.log) em <JITTERBIT_HOME>/Tomcat/temp (ou, em versões mais antigas, na pasta Tomcat diretamente), consumindo o espaço em disco do host do agente. Isso afeta agentes privados do Windows em versões anteriores à 11.49.

• Causas possíveis:

  • O coletor de estatísticas de disco AgentStats do agente trava a JVM enquanto coleta métricas de disco. Isso afeta agentes em versões anteriores à 11.49.
  • Em agentes executando 11.47 ou 11.48, uma falha separada no Process Engine pode produzir os mesmos arquivos de falha.

• Resolução: Atualize o agente privado para a versão 11.49 ou posterior, o que resolve ambas as causas.

  Se uma atualização imediata não for possível e os arquivos de falha forem provenientes da coleta de estatísticas de disco, você pode desativar essa coleta como uma solução alternativa (a flag DiskStatsEnabled está disponível no agente 11.44.1 e posterior):

  1. Em jitterbit.conf, adicione:

     [AgentStats]
     DiskStatsEnabled=false
     

  2. Reinicie os serviços do agente. Os arquivos de falha existentes podem ser excluídos com segurança para recuperar espaço em disco.

  3. Se você estiver na versão 11.47 ou 11.48 e os arquivos de falha continuarem, atualize para 11.49 ou entre em contato com o suporte da Jitterbit para uma solução alternativa.

Problemas de banco de dados

Falhas de conexão TranDb

• Sintoma: As operações falham com erros que fazem referência ao banco de dados PostgreSQL interno do agente privado, ou os serviços internos do agente falham ao iniciar porque o limite de conexões foi atingido. Falhas repetidas também podem inundar ProcessEngine.log, fazendo com que cresça para muitos 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 possíveis:

  • O limite max_connections do PostgreSQL interno, ou o limite max_db_connections do PgBouncer, é muito baixo para a carga de trabalho do agente.
  • As operações estão se acumulando sob carga pesada ou uma desaceleração de rede ou de endpoint, mantendo conexões de banco de dados até que o pool do PgBouncer esteja esgotado (query_wait_timeout).
  • Em um agente Windows, o IP Helper está interferindo nas conexões locais do banco de dados do agente.

• Resolução:

  • Versões recentes do agente vêm com limites de conexão do PostgreSQL e PgBouncer mais altos por padrão, então primeiro confirme se o agente está em uma versão atual. Se um agente atual ainda esgotar seu limite de conexão, entre em contato com o suporte da Jitterbit para aumentá-lo sob orientação de suporte. As instâncias do PostgreSQL e PgBouncer incluídas devem ser alteradas apenas sob orientação de suporte.
  • Se os limites já forem adequados, investigue o que está mantendo as conexões abertas: revise a carga do host do agente e qualquer lentidão de rede ou de endpoint que esteja acumulando operações.
  • Em um agente Windows, desative o IP Helper. Veja problema de IPv6 no Windows.

O PostgreSQL empacotado no Linux usa MD5 em vez de SCRAM-SHA-256

• Sintoma: Você deseja mudar o método de autenticação do PostgreSQL empacotado em um agente privado Linux de MD5 para SCRAM-SHA-256, mas o agente continua a usar MD5.

• Causas possíveis:

  • MD5 é a criptografia de senha padrão para o PostgreSQL empacotado em agentes privados Linux. SCRAM-SHA-256 foi o padrão apenas nas versões 12.6 e 12.7; a versão 12.8 reverteu o padrão para MD5. Ao atualizar um agente Linux de 12.6 ou 12.7, o instalador solicita que você redefina a criptografia para MD5 ou mantenha SCRAM-SHA-256; veja Atualizar um agente Linux.
  • Editar pg_hba.conf e postgresql.conf sozinhos não completa a troca. O PgBouncer também deve ser reconfigurado com o hash do verificador SCRAM, ou o agente falha ao iniciar.

• Resolução: Para mudar um agente privado Linux para SCRAM-SHA-256, siga o guia SCRAM no PostgreSQL. SCRAM-SHA-256 é um método de autenticação mais forte, enquanto MD5 é mais performático, então a troca é uma mudança deliberada e em várias etapas: o guia reconfigura o PostgreSQL empacotado, atualiza as senhas dos usuários e reconfigura o PgBouncer com o novo hash. Reconfigurar a instância empacotada é a maneira suportada de habilitar o SCRAM. Não substitua a instância empacotada pelo seu próprio servidor PostgreSQL para obter SCRAM: agentes que usam uma instância PostgreSQL diferente da empacotada não são suportados.

PostgreSQL: Desligamento rápido administrativo

• Sintoma: Todas as operações falham porque o banco de dados do agente está indisponível (as operações podem ficar em status Pendente), e o log do PostgreSQL registra um desligamento rápido:

  received fast shutdown request
  

As operações de conexão também podem relatar FATAL: terminating connection due to administrator command.

• Possíveis causas:

  • Uma ação externa ou do sistema parou ou reiniciou o PostgreSQL: uma reinicialização do SO, uma atualização do Windows ou uma tarefa agendada, ou uma ferramenta de monitoramento ou backup que reinicia serviços.
  • O host do agente ficou sem CPU ou memória, fazendo com que o Tomcat falhasse e levando o PostgreSQL junto.

• Resolução:

  • Reinicie os serviços do PostgreSQL e do agente Jitterbit (ou reinicie o host do agente) para recuperar. Se as operações permanecerem travadas em um estado Pendente ou Executando após o PostgreSQL voltar, entre em contato com o suporte Jitterbit, pois o pool de conexões do banco de dados do agente pode não ter se recuperado.
  • Identifique o que parou o PostgreSQL: verifique o log de eventos do SO (no Windows, Visualizador de Eventos) em torno do momento da falha para reinicializações, atualizações, tarefas agendadas, falhas de serviços ou ferramentas de backup e monitoramento que reiniciam serviços. Previna ou reprograma o que estiver parando, e configure o serviço PostgreSQL para reiniciar automaticamente em caso de falha.
  • Verifique a CPU e a memória do host do agente. Se os serviços Jitterbit estiverem falhando sob carga, consulte Loop de reinicialização do serviço do agente e Espaço de heap Java: OutOfMemoryError.

Rede e conectividade

Falha na negociação do certificado (TLS)

• Sintoma: As operações conectando-se a pontos finais seguros falham durante a negociação TLS, com erros 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
  

• Possíveis causas:

  • O ponto final usa renegociação TLS legada, que o agente bloqueia por padrão.
  • O agente e o ponto final não conseguem negociar uma versão ou cifra TLS comum. Agentes das versões 11.x e 12.x possuem bibliotecas de segurança diferentes, portanto, um ponto final que falha ao conectar em um agente 11.x pode ter sucesso em um agente 12.x.
  • O certificado do ponto final (ou um de seus intermediários) não é confiável pelo agente porque sua CA emissora não está no armazenamento de confiança cacerts do JRE do agente.

• Resolução: A partir do host do agente, execute o seguinte para confirmar qual versão do TLS o endpoint negocia e se o handshake é bem-sucedido no nível da rede:

  openssl s_client -connect hostname:port
  

  Em seguida, aplique a correção que corresponde ao erro:

  • Se o erro for unsafe legacy renegotiation disabled, defina AllowUnsafeLegacyRenegotiation=true na seção [Settings] do jitterbit.conf e reinicie o agente. Essa configuração requer a versão 11.39 ou posterior do agente.
  • Se o erro for PKIX path building failed: unable to find valid certification path to requested target, o certificado do endpoint (ou um de seus intermediários) não está no armazenamento de confiança cacerts do JRE do agente. Use keytool -import no cacerts do JRE do agente (senha padrão changeit) para importar o(s) certificado(s) ausente(s), em seguida, reinicie os serviços do agente. Para um banco de dados SQL Server acessado através de uma conexão Database, você também pode resolver isso nas configurações do driver da conexão em vez do armazenamento de confiança, tanto em agentes na nuvem quanto privados. Veja SQL Server: A conexão falha com um erro de caminho de certificado PKIX.
  • Se uma falha de negociação ou handshake do TLS persistir, particularmente em um agente 11.x, atualize para um agente 12.x atual, que inclui bibliotecas de segurança atualizadas e um armazenamento de confiança de certificados atualizado.

A conexão com o sandbox do Salesforce falha devido a incompatibilidade de certificado

• Sintoma: Uma conexão de agente privado a um endpoint que requer Server Name Indication (SNI) falha devido a uma incompatibilidade de certificado, enquanto a mesma conexão é bem-sucedida a partir de um grupo de agentes na nuvem ou de um teste direto com openssl ou curl no host do agente. O caso mais comum é uma URL de sandbox do Salesforce terminando em .sandbox.my.salesforce.com:

  O certificado para <your-domain.sandbox.my.salesforce.com> não corresponde a nenhum dos nomes alternativos do assunto: ...
  

  Outros endpoints afetados incluem hosts que compartilham um único IP por trás de hospedagem virtual.

• Causa: O handshake TLS não está incluindo a extensão SNI, então o servidor retorna um certificado padrão em vez do que corresponde ao host solicitado. Para um sandbox do Salesforce, o balanceador de carga retorna o certificado de produção, cujos nomes não cobrem *.sandbox.my.salesforce.com. O SNI é enviado por padrão, então quando está ausente, algo está suprimindo ou removendo-o.

• Resolução:

  1. Confirme se o SNI é a causa. A partir do host do agente, compare o certificado retornado com e sem SNI:

     openssl s_client -connect HOST:443 -servername HOST   # certificado quando SNI é enviado
     openssl s_client -connect HOST:443                    # certificado quando SNI é omitido
     

     Se o primeiro retornar o certificado correto e o segundo retornar o incorreto, o SNI é a causa.

  2. Verifique se o SNI está explicitamente desativado nas opções Java do agente e remova-o se estiver. No Windows, abra o Editor do Registro em HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Apache Software Foundation\Procrun 2.0\Jitterbit Tomcat Server\Parameters\Java e edite o valor Options; no Linux, verifique JAVA_OPTS em /etc/sysconfig/jitterbit. Remova -Djsse.enableSNIExtension=false se presente (essa configuração suprime o SNI). Reinicie os serviços do agente.

  3. Se o SNI ainda estiver ausente após isso, um dispositivo de rede, proxy ou pilha de rede de VM entre o agente e o endpoint está removendo-o. Sua equipe de rede deve permitir a extensão SNI.

  Se a conexão também falhar a partir de um grupo de agentes em nuvem, o SNI não é a causa. O certificado do servidor pode não listar o host em seus Nomes Alternativos do Assunto. Para o Salesforce, adicione a URL MyDomain do sandbox ao certificado do Salesforce, ou veja Incompatibilidade de Nome Alternativo do Assunto do Certificado (SAN).

FTP: Conexão de dados expirou

• Sintoma: O login FTP é bem-sucedido, mas a listagem de arquivos ou a transferência de arquivos trava e expira.

• Possíveis causas:

  • O modo de conexão FTP (ativo vs. passivo) é incompatível com a configuração da rede ou do firewall.
  • O intervalo de portas passivas definido no servidor FTP não está aberto no firewall corporativo.

• Solução:

  • Nas configurações de conexão FTP, altere a caixa de seleção Modo Passivo. O modo passivo é geralmente preferido para agentes atrás de um firewall.
  • Confirme com sua equipe de rede que o intervalo de portas passivas configurado no servidor FTP está aberto no firewall entre o agente e o servidor FTP.
  • Para capturar logs detalhados de nível de conexão, ative o registro de depuração do curl definindo CurlDebugDir na seção [Settings] de jitterbit.conf. Veja os logs do Curl.

SSH: Conexão SFTP falha devido ao caminho do arquivo de chave incorreto

• Sintoma: As operações SFTP falham em um agente Windows, mesmo que os arquivos de chave SSH estejam instalados corretamente.
• Causa: Os valores de caminho PrivateKeyFile e PublicKeyFile na seção [SSH] de jitterbit.conf usam separadores de barra invertida do Windows (\), que não são suportados.
• Solução: Use barras normais em todos os caminhos de arquivos de chave SSH em jitterbit.conf, mesmo no Windows (por exemplo, C:/jitterbit/keys/id_rsa). Veja [SSH].

Configurações SSH SFTP ausentes ou na seção errada do jitterbit.conf

• Sintoma: As operações SFTP que usam uma chave privada para autenticação falham com um erro de arquivo de chave privada vazio após uma atualização ou reinício do agente. As configurações de chave SSH adicionadas ao jitterbit.conf local também podem parar de ter efeito após o reinício do agente.

  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
  

• Possíveis causas:

  • A configuração do agente remoto está habilitada (está ativada por padrão), portanto, as configurações gerenciadas através da aba Configuração do Jitterbit no Console de Gerenciamento têm precedência. As configurações da chave SSH adicionadas apenas ao jitterbit.conf local podem não ter efeito ou podem não ser mantidas após a reinicialização do agente.
  • As configurações da chave SSH (PrivateKeyFile, PrivateKeyPassphrase, PublicKeyFile) estão na seção errada. Versões mais recentes do agente analisam estritamente e ignoram as configurações SSH colocadas fora da seção [SSH] (por exemplo, sob [SSL]).

• Resolução:

  1. Se a configuração remota estiver habilitada, adicione as configurações da chave SSH lá: abra o painel de Detalhes do grupo de agentes para o grupo de agentes, selecione a aba Configuração do Jitterbit e adicione-as na seção SSH. Veja Configuração do Jitterbit.
  2. Se o jitterbit.conf local for a fonte de configuração, confirme se as configurações da chave SSH estão colocadas sob [SSH] (não [SSL]).
  3. Reinicie os serviços do agente.
  4. Para solução de problemas adicionais de autenticação de chave SFTP (campos de senha, frase secreta, formato da chave), veja SFTP "Login denied. Authentication failure." ao usar chaves SSH.

Falha na autenticação SFTP para um servidor específico (incompatibilidade de cifra cURL)

• Sintoma: Uma conexão SFTP usando autenticação de chave SSH falha em um agente privado com Login denied. Authentication failure., mas outras conexões SFTP do mesmo agente (usando a mesma chave) têm sucesso, e conectar ao servidor que falha a partir da linha de comando do SO também tem sucesso.

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

• Causa: O servidor SFTP requer cifras SSH, troca de chaves ou algoritmos de chave de host mais novos que a biblioteca cURL incluída em versões mais antigas do agente não suporta. Servidores que ainda aceitam os algoritmos mais antigos continuam a funcionar, razão pela qual a mesma chave tem sucesso contra outros hosts e a partir da linha de comando do SO.
• Resolução: Atualize o agente privado para a versão 11.37 ou posterior, que inclui uma biblioteca cURL atualizada com suporte para cifras SSH, troca de chaves e algoritmos de chave de host atuais.

Proxy HTTPS: A autenticação básica através do túnel do proxy falha

• Sintoma: Quando o agente se conecta através de um proxy HTTPS que requer autenticação básica, as conexões através do túnel do proxy falham com um erro de autenticação.
• Causa: Versões modernas do JDK desativam a autenticação básica durante o tunelamento de proxy HTTPS por padrão. A propriedade da JVM jdk.http.auth.tunneling.disabledSchemes bloqueia a autenticação básica, a menos que explicitamente liberada.
• Resolução: Adicione -Djdk.http.auth.tunneling.disabledSchemes="" a CATALINA_OPTS antes de iniciar o Tomcat. Para instruções passo a passo para Windows, Linux e Docker, veja Permitir autenticação básica durante o tunelamento de proxy HTTPS.

Agentes privados em redes restritas: Conectividade apenas de saída

• Sintoma: Ao implantar agentes privados atrás de um firewall corporativo rigoroso ou em um ambiente restrito (por exemplo, OpenShift) ao lado de um gateway de API privado, as equipes de rede às vezes perguntam quais portas de entrada devem ser abertas no agente para que o Harmony ou o gateway possam alcançá-lo.

• Causa: Agentes privados não requerem que portas de entrada sejam abertas, devido à forma como a conectividade do agente funciona:

  • Agentes privados não aceitam conexões de entrada do Harmony ou de um gateway de API privado. O agente estabelece uma conexão WebSocket de saída com o Harmony via HTTPS (porta 443). Todo o tráfego do Harmony e do gateway para o agente é roteado de volta por meio dessa conexão pré-estabelecida.
  • Um gateway de API privado envia solicitações de API para o Harmony, e o Harmony roteia a solicitação para o agente apropriado através do WebSocket de saída existente. O agente roteia a carga útil da resposta da API de volta para o gateway de API privado, portanto, o agente também deve ser capaz de alcançar o gateway (diretamente ou através de seu balanceador de carga em uma implantação de múltiplos gateways).

• Resolução:

  • Abra o HTTPS de saída (porta 443) do host do agente para os URLs da região Harmony. A conexão é atualizada para WSS (WebSocket seguro) para comunicação bidirecional contínua. Nenhuma porta de entrada precisa ser aberta no host do agente para Harmony ou para o gateway.
  • Ao configurar o firewall, adicione à lista de permissões os serviços Jitterbit específicos da região listados em Comunicação de saída, a seção que se aplica a um agente privado atrás de um firewall.
  • Se o agente foi configurado para usar portas não padrão (personalizadas), permita também essas portas através do firewall corporativo. Veja Portas de rede.
  • Se um gateway de API privado estiver implantado, também permita a conectividade de saída de cada host de agente para o gateway (diretamente ou através do balanceador de carga em uma implantação de múltiplos gateways). O agente se conecta ao gateway para retornar a carga útil da resposta da API. Para o fluxo completo de requisição, veja Arquitetura do sistema do gateway de API privado.

API personalizada retorna 504, mas o log de operação mostra sucesso

• Sintoma: Uma API personalizada retorna um timeout de gateway 504, mas o log de operação na página Runtime do Console de Gerenciamento mostra que a operação foi concluída com sucesso.
• Causa: Quando uma carga útil de requisição ou resposta (cabeçalhos mais corpo, comprimido) excede aproximadamente 1 KB, o gateway de API em nuvem Jitterbit estágios a carga útil, e o agente privado faz uma conexão de saída para o host jitterbitsysservice de sua região para baixar a carga útil da requisição (ou fazer upload da carga útil da resposta) antes de concluir a operação. Se o host do agente não conseguir acessar esse host, a transferência expira e a API retorna um 504, mesmo que a operação em si tenha sido executada. A verificação padrão de conexão do agente não verifica a conectividade com o host jitterbitsysservice, portanto, o agente pode parecer totalmente conectado enquanto esse host permanece bloqueado.
• Resolução:
  1. Adicione o host jitterbitsysservice para sua região (por exemplo, jitterbitsysservice.jitterbit.net) e seus endereços IP estáticos à lista de permissões de saída no firewall do host do agente privado. Veja Informações sobre a lista de permissões do Jitterbit para os URLs e IPs específicos da região.
  2. Verifique a conectividade executando um teste HTTP do host do agente para o URL jitterbitsysservice de sua região, e então confirme que a API não expira mais.

Problema de IPv6 no Windows

• Sintoma: Alguns agentes enfrentam problemas de conectividade quando o IPv6 está habilitado no host Windows. Isso pode se manifestar, por exemplo, como operações travadas em um estado Pendente com um ProcessEngine.log crescendo rapidamente, quando o serviço IP Helper falha e o agente perde a conexão com o banco de dados interno.

• Solução: Desative tanto o IPv6 quanto o IP Helper no host Windows.

  Desative o IPv6 da seguinte forma:

  1. Abra Painel de Controle > Rede e Internet > Conexões de Rede.
  2. Abra as Propriedades da conexão de rede.

  3. Desmarque a caixa para Protocolo de Internet Versão 6 (TCP/IPv6):

     

  Desative o IP Helper da seguinte forma:

  1. Abra Serviços.
  2. Localize IP Helper, clique com o botão direito e selecione Propriedades.

  3. Clique em Parar, depois defina o Tipo de inicialização como Desativado:

     

Azure VM: Conexões perdidas e erros de WebSocket/I/O

Esta seção aborda a solução de problemas para agentes privados instalados em máquinas virtuais (VMs) do Microsoft Azure. Para ajustes gerais de desempenho, consulte Ajuste de desempenho do agente privado.

Conexões perdidas

O Azure define o tempo limite ocioso do WebSocket para 4 minutos, enquanto o intervalo de batimento cardíaco padrão do agente privado é de 5 minutos. Para resolver conexões perdidas, reduza o intervalo de batimento cardíaco:

1. Abra jitterbit-agent-config.properties em um editor de texto:

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

2. Encontre a configuração agent.heart.beat.interval:

   #Intervalo de batimento cardíaco do agente (EM MINUTOS)
   agent.heart.beat.interval=5
   

3. Altere o valor para agent.heart.beat.interval=3.

4. Salve o arquivo e reinicie o agente.

Erros de WebSocket e I/O

Erros de WebSocket e I/O podem ser resolvidos atualizando o tempo limite ocioso do IP da VM do Azure, o tempo limite ocioso TCP do gateway NAT e o tempo limite de fluxo da rede virtual (VNET), cada um para 15 minutos. Isso é abordado nos seguintes passos.

Identificar erros relevantes

Verifique os logs de operação e jitterbit-agent.log em busca das seguintes mensagens.

Erros de log de operação:

A operação "Exemplo de Operação" foi concluída com sucesso.

Nenhuma mensagem encontrada ao remover a mensagem do cache para: Informações da Mensagem: AgentId: 000001 AgentGroupId: 000001 MessageId: XXX Versão da Mensagem (Agente): XXXX Versão da Mensagem (Harmony): XXX Contador (Harmony): 1 Timestamp Enviado (Harmony):2024-01-20 11:55:00.700 , a mensagem será tentada novamente mais tarde OperationInstanceGUID: XXX

A mensagem de execução não pôde alcançar o agente.

Erros de log do agente:

2024-01-20 12:00:00 request handler thread #10642  INFO org.jitterbit.integration.server.api.util.AgentRetryExecutor:53 - Recepção de Mensagem do Agente (OperationInstanceGUID: XXX) falhou. Tentando novamente....
2024-01-20 12:00:00 request handler thread #10642 ERROR org.jitterbit.integration.server.api.util.AgentRetryExecutor:55 - org.springframework.web.client.ResourceAccessException: Erro de I/O na solicitação PUT para "https://na-east.jitterbit.com/jitterbit-cloud-restful-service/agent/ackmsgreceipt": Tempo de leitura esgotado; exceção aninhada é java.net.SocketTimeoutException: Tempo de leitura esgotado

E:2024-01-20 12:00:00 request handler thread #884 ERROR org.jitterbit.integration.server.messaging.agent.listener.AgentMessageListener:231 - Nenhuma mensagem encontrada ao remover a mensagem do cache para: Informações da Mensagem: AgentId: 000001 AgentGroupId: 000001 MessageId: XXX Versão da Mensagem (Agente): XXXX Versão da Mensagem (Harmony): XXX Contador (Harmony): 1 Timestamp Enviado (Harmony):2024-01-20 11:55:00.700 , a mensagem será tentada novamente mais tarde OperationInstanceGUID: XXX

Parar o agente com dreno

Parar com dreno o agente antes de atualizar qualquer configuração de tempo limite. Se houver mais de um agente no grupo afetado, pare com dreno todos eles.

Isolar recursos do agente

Recomenda-se que a VM do agente e seus recursos associados (VNET, IP, gateway NAT, NIC e NSG) sejam separados em seu próprio grupo de recursos no Azure.

Atualizar o tempo limite ocioso do IP

1. No portal do Azure, navegue até o grupo de recursos associado à VM do agente.

2. Clique no item de IP associado à VM:

   

3. Clique em Configuração e defina Tempo limite ocioso (minutos) para 15:

   

Atualizar o tempo limite ocioso TCP do gateway NAT

1. No portal do Azure, navegue até o grupo de recursos associado à VM do agente.

2. Clique no item do gateway NAT associado à VM e ao IP. O gateway NAT associado também está listado no item de IP em Visão geral ao lado de Associado a.

3. Clique em Configuração e defina Tempo limite ocioso TCP (minutos) para 15.

Atualizar o tempo limite de fluxo do VNET

1. No portal do Azure, navegue até o grupo de recursos associado à VM do agente.

2. Clique no item do VNET associado à VM:

   

3. Em Visão geral, clique em Configurar ao lado de Tempo limite de fluxo:

   

4. Ative Ativar tempo limite de fluxo e defina Tempo limite de fluxo (minutos) para 15:

   

5. Clique em Salvar.

Reiniciar o agente

1. No portal do Azure, reinicie a VM do agente.

2. Inicie o agente parado (Windows | Linux).

Observabilidade

A observabilidade nativa não está mostrando dados

• Sintoma: Após habilitar a observabilidade nativa, a aba Métricas da página Agentes do Console de Gerenciamento não mostra dados, mostra dados incompletos ou os gráficos permanecem vazios após vários minutos de espera.

• Causas possíveis:

  • A seção [AgentMetrics] em jitterbit.conf não possui Enabled=true, impedindo que o serviço de métricas seja executado.
  • Nem todas as configurações necessárias na seção [AgentCapability] estão definidas como true.
  • Os serviços do agente não foram reiniciados após fazer alterações na configuração.
  • O host do agente não consegue acessar a nuvem Harmony, impedindo o envio de métricas.
  • O serviço de métricas está configurado para se conectar à instância PgBouncer embutida do agente privado em uma porta diferente da que o PgBouncer está realmente usando, de modo que o serviço de métricas não consegue se conectar a ele e as métricas são coletadas apenas parcialmente. Essa incompatibilidade de porta pode ocorrer após certas instalações ou atualizações do agente.
  • Antes da versão 12.9 do agente, instalar um agente privado como um usuário não-root no Linux não provisionava o PgBouncer, então o serviço nunca começou e seu status sempre aparece como não saudável.

• Resolução:

  • Verifique se jitterbit.conf contém todas as configurações necessárias das seções [AgentMetrics] e [AgentCapability]. Veja o exemplo completo de configuração em configuração de observabilidade nativa.
  • Verifique metrics.log e metrics_service.log no diretório de logs do agente para erros. Esses logs registram o status do serviço de métricas e indicam se as métricas estão sendo coletadas e enviadas.
  • Reinicie os serviços do agente se alguma alteração na configuração foi feita.
  • Verifique se o host do agente consegue acessar a nuvem Harmony. Veja Agente offline ou inacessível. Se o agente se conectar através de um proxy, veja Métricas do agente ausentes quando o agente se conecta através de um proxy HTTP.
  • Se as métricas forem coletadas apenas parcialmente e os passos acima não resolverem, entre em contato com o suporte da Jitterbit para verificar se a porta de conexão do PgBouncer do serviço de métricas corresponde à porta configurada do PgBouncer.
  • Para um novo agente privado Linux não-root, use a versão 12.9 ou posterior, onde o PgBouncer é corretamente provisionado durante a instalação. Atualizar um agente Linux não-root existente para 12.9 ou posterior não provisiona o PgBouncer retroativamente; o agente deve ser instalado novamente.

Métricas do agente ausentes quando o agente se conecta através de um proxy HTTP

• Sintoma: O agente privado se conecta ao Harmony com sucesso através de um proxy HTTP configurado, mas a aba Métricas da página Agentes do Console de Gerenciamento não mostra dados. O arquivo metrics.log pode conter entradas como Client.Timeout exceeded while awaiting headers.
• Causa: O agente envia métricas via HTTPS usando uma conexão separada que não herda a configuração do proxy do agente. Se o proxy suporta apenas HTTP, ou não está configurado para o tráfego de métricas do agente, as métricas não conseguem alcançar o Harmony, mesmo que o agente em si se conecte com sucesso.
• Resolução:
  1. Confirme se o proxy suporta HTTPS. As métricas do agente são enviadas via HTTPS, portanto, um proxy que lida apenas com tráfego HTTP as bloqueia. Habilitar HTTPS no proxy resolve o problema.
  2. Se você não puder habilitar HTTPS no proxy, ou se as métricas ainda estiverem ausentes após habilitá-lo, o tráfego de métricas do agente precisa de sua própria configuração de proxy, separada da do agente. Entre em contato com o suporte da Jitterbit para configurá-lo.

O agente Datadog falha ao iniciar após a instalação do Docker

• Sintoma: Após instalar o agente Datadog dentro de um contêiner Docker como parte da configuração de observabilidade do Datadog, o agente Datadog falha ao iniciar.
• Causa: Um problema conhecido do Datadog faz com que o agente falhe na inicialização quando o arquivo de configuração do agente de segurança não existe.

• Resolução: Copie o arquivo de configuração de exemplo do agente de segurança:

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

  Em seguida, inicie o agente Datadog. Observe que no Docker, o agente Datadog não inicia automaticamente com o contêiner e deve ser iniciado manualmente após cada inicialização do contêiner:

sudo datadog-agent run

Problemas de Sistema e SO

Erro do Servidor Apache: Nenhum ConfigArgs instalado

• Sintoma: O agente retorna:

  No Installed ConfigArgs for the Service "Jitterbit Apache Server"
  

• Causa: A conta que executa o servidor Apache Jitterbit não tem acesso total ao diretório de instalação do Jitterbit.

• Resolução: Conceda à conta de serviço acesso total à pasta de instalação do Jitterbit e reinicie os serviços.

Apache/Tomcat: APPARENT DEADLOCK

• Sintoma: Sob carga sustentada, o agente para de processar operações e pode aparecer como parando no Console de Gerenciamento. O log do agente contém:

  ThreadPoolAsynchronousRunner: APPARENT DEADLOCK
  

  O log também pode mostrar An existing connection was forcibly closed by the remote host para o banco de dados PostgreSQL do agente. Reiniciar o agente restaura a operação normal temporariamente, após o que o deadlock recorre sob carga.

• Possíveis causas:

  • O pool de conexões do banco de dados do agente entra em deadlock quando o banco de dados PostgreSQL interno fica sem conexões disponíveis sob carga pesada.
  • O pool de conexões de banco de dados Java do agente (mostrado como c3p0 no log) não consegue se recuperar após uma conexão de banco de dados ser brevemente perdida, por exemplo, durante uma interrupção de rede transitória, mesmo que o PostgreSQL em si permaneça saudável e responsivo com os timeouts padrão.
  • Processos obsoletos do Jitterbit estão segurando threads e conexões de banco de dados. Isso pode ocorrer quando um agente é atualizado enquanto operações ainda estão em execução, ou quando os serviços são parados sem que todos os processos do Jitterbit terminem corretamente.
  • O host do agente está sobrecarregado por atividade de pico, ou sua CPU está sendo estrangulada. Por exemplo, uma instância de nuvem com capacidade de explosão (como um tipo t3 da AWS) estrangula sua CPU uma vez que seus créditos de explosão são esgotados, o que pode privar o PostgreSQL interno sob carga.

• Resolução:

  • Pare todos os serviços do Jitterbit, finalize qualquer processo do Jitterbit que ainda esteja em execução e, em seguida, reinicie os serviços para eliminar o deadlock.
  • Se o deadlock estiver no pool de conexões Java (c3p0) e o PostgreSQL estiver saudável, mude o agente para seu pool de conexões interno em C++ definindo UseInternalPooling=true na seção [DbInfo] de jitterbit.conf, e então reinicie o agente. O pool interno se recupera de conexões perdidas ou obsoletas de forma mais confiável. Em instalações novas de agentes privados do Windows versão 12.5 e posteriores, isso já está habilitado por padrão.
  • Reduza a carga no agente: agende operações para evitar picos de atividade, adicione agentes ao grupo de agentes para balanceamento de carga e confirme se o host atende aos requisitos do sistema. Para hosts em nuvem, use um tipo de instância com desempenho de CPU sustentado (não explosivo).
  • Antes de atualizar um agente, drain stop ele e deixe as operações em execução terminarem, para que nenhum processo fique segurando conexões de banco de dados durante a atualização. Em ambientes movimentados, permita tempo extra para a conclusão do drain stop.

O serviço de limpeza não consegue remover arquivos de log bloqueados no Windows

• Sintoma: Os arquivos de log em um agente privado do Windows crescem indefinidamente, e o serviço de limpeza não os remove. O log do serviço de limpeza relata um erro 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 possíveis:

  • Um processo do agente está mantendo o arquivo aberto. No Windows, o serviço de limpeza não pode remover um arquivo que está em uso, e o Tomcat mantém seus arquivos de log stdout e stderr abertos enquanto está em execução.
  • Software de terceiros (antivírus ou um agente de monitoramento) está mantendo um bloqueio em arquivos no diretório de log do agente.

• Resolução:

  • Edite CleanupRules.xml para encurtar a retenção (FileAge) dos diretórios de log afetados, para que os arquivos sejam removidos prontamente assim que não estiverem mais em uso. Reinicie o agente após editar o arquivo.
  • Exclua os logs stdout e stderr do Tomcat, que são continuamente gravados, das regras de limpeza, para que o serviço não tente repetidamente arquivos que permanecem bloqueados enquanto o agente está em execução.
  • Se software de terceiros estiver envolvido, adicione os diretórios de instalação e log do Jitterbit à sua lista de exclusão.
  • Se os logs continuarem crescendo mesmo com regras de limpeza válidas, entre em contato com o suporte do Jitterbit.

Linux: Serviços do agente falham ao iniciar após uma reinicialização ("postmaster.pid não existe")

• Sintoma: Após reiniciar um host de agente privado Linux, os serviços do agente falham ao iniciar. Executar sudo jitterbit status mostra que o agendador e outros serviços não estão em execução, e os logs do agente (ou console) incluem erros como:

  postmaster.pid does not exist
  

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

• Causa: As permissões de arquivo no diretório de dados do PostgreSQL incluído são muito permissivas. O PostgreSQL requer que o diretório de dados seja 700 (apenas proprietário). Se as permissões forem mais frouxas (por exemplo, 755 ou 777), o PostgreSQL se recusa a iniciar, o que impede o restante do agente de iniciar.

• Resolução:

  1. Confirme que /opt/jitterbit e seus subdiretórios são de propriedade do usuário e grupo jitterbit:

     sudo chown -R jitterbit:jitterbit /opt/jitterbit
     

  2. Defina o diretório de dados do PostgreSQL como 700:

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

  3. Inicie os serviços do agente:

     sudo /etc/init.d/jitterbit start
     

Linux: O antivírus remove PgBouncer, o agente falha ao autenticar no banco de dados incluído

• Sintoma: Após migrar um agente privado Linux para um novo host (ou realizar uma instalação limpa), os serviços do agente falham ao iniciar. O postgresql.log mostra:

  [FATAL] password authentication failed for user "jitterbit"
  

  O log do agente mostra que não consegue se conectar ao banco de dados. A falha persiste mesmo após desinstalação e reinstalação completas.

• Causa: Um antivírus baseado em host ou produto de proteção de endpoint detecta o binário PgBouncer incluído como suspeito e o remove ou coloca em quarentena. Sem o PgBouncer, o agente não consegue se autenticar em seu banco de dados PostgreSQL interno.

• Resolução:

  1. Desative temporariamente o antivírus ou produto de proteção de endpoint no host do agente.
  2. Adicione o diretório de instalação do Jitterbit (tipicamente /opt/jitterbit) à lista de exclusões do antivírus.

  3. Reinstale o agente. No RHEL/CentOS:

     sudo dnf reinstall jitterbit-agent
     

  4. Inicie os serviços do agente e confirme a operação normal, em seguida, reative o antivírus com a exclusão em vigor.

As verificações de segurança sinalizam log4j-over-slf4j.jar como uma vulnerabilidade do Log4j 1.x

• Sintoma: Uma verificação de segurança de uma instalação de agente privado sinaliza arquivos como log4j-over-slf4j-1.7.21.jar como uma vulnerabilidade do Log4j 1.x em fim de vida.
• Resolução: Nenhuma ação é necessária. log4j-over-slf4j.jar não é Log4j 1.x. Ele faz parte da estrutura de registro SLF4J e atua como uma ponte que redireciona chamadas de bibliotecas de terceiros escritas contra a API Log4j 1.x para a estrutura de registro atual e suportada do agente. O arquivo não contém o código vulnerável do Log4j 1.x. Sua presença é a mitigação do agente contra a exposição ao Log4j 1.x, não uma instância da vulnerabilidade.

Docker

Geral

Os seguintes pontos se aplicam a problemas relacionados ao Docker:

• Um agente privado do Docker não iniciará se o diretório conf contiver tanto um arquivo credentials.txt quanto um arquivo register.json.

• Executar agentes privados no Kubernetes não é oficialmente certificado pela Jitterbit, e a Jitterbit não validou uma configuração de Kubernetes pronta para produção. O gráfico Helm e os passos do Kubernetes são fornecidos apenas como um ponto de partida para testes ou desenvolvimento adicional.

O agente falha ao reiniciar com erros de autenticação após a desregistro

• Sintoma: Um agente configurado com deregisterAgentOnDrainstop=true (ou a variável de ambiente AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP) falha ao reiniciar após ser parado. Isso se aplica a agentes Docker que usam um volume persistente para /opt/jitterbit/Resources, e a agentes Linux não conteinerizados.

• Causa: Quando o agente para com deregisterAgentOnDrainstop=true, ele se desregistra do Harmony, mas o arquivo credentials.txt agora inválido permanece no disco. Ao reiniciar, o agente tenta usar as credenciais obsoletas e falha na autenticação.

  Nota

  A partir da versão 12.4 do agente Docker, reiniciar o contêiner quando deregisterAgentOnDrainstop=true está habilitado desregistra automaticamente o agente existente e registra um novo. Os passos abaixo se aplicam a agentes Docker em versões anteriores e a agentes Linux em qualquer versão.

• Solução: Remova o arquivo credentials.txt obsoleto e, em seguida, reinicie o agente para acionar um novo registro.

  Em um agente Linux não conteinerizado, remova o arquivo diretamente:

  rm /opt/jitterbit/Resources/credentials.txt
  

  Em um agente Docker, remova o arquivo do volume montado:

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

  Substitua VOLUME_NAME pelo nome do volume Docker sob o qual /opt/jitterbit/Resources está montado.

Serviço de escuta

"O cluster não atingiu o tamanho mínimo necessário"

• Sintoma: Operações usando o Serviço de escuta falham com:

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

• Causas possíveis:

  • Poucos agentes no grupo de agentes estão em execução e conectados ao cluster. Para um grupo de \(N\) agentes, contados independentemente de cada agente estar em execução, \((N / 2) + 1\) agentes (arredondados para baixo) devem estar em execução e fazer parte do cluster.
  • Um ou mais agentes perderam a conexão com o cluster e não conseguiram se reconectar, reduzindo o número de agentes em execução e conectados abaixo do necessário \((N / 2) + 1\).
  • Uma interrupção na rede dividiu o grupo de agentes em múltiplos clusters menores. Por exemplo, em um grupo de 4 agentes, uma divisão na rede pode produzir dois clusters de 2 agentes cada; nenhum atende ao requisito de \((N / 2) + 1\) de 3, então ambos relatam o erro, mesmo que todos os agentes estejam em execução.

• Resolução:

  • Confirme que \((N / 2) + 1\) dos agentes no grupo estão em execução e fazem parte do cluster, onde \(N\) é o número de agentes registrados no grupo de agentes, independentemente de cada um estar em execução ou não. Por exemplo, um grupo de 4 agentes requer 3, e um grupo de 5 agentes também requer 3. Para ver quais agentes se juntaram, use a API REST do Serviço de escuta para mostrar o status do cluster.
  • Verifique se as portas TCP 5701 e 5801 estão abertas entre todos os hosts de agentes e não estão bloqueadas por regras de antivírus ou firewall.
  • Se o cluster estiver fora do ar e as mensagens permanecerem não processadas com a persistência habilitada, restaure o cluster manualmente. Veja Restauração do cluster após falha do agente.

  Nota

  Um número ímpar de agentes no grupo de agentes é recomendado, mas não obrigatório. Com um número par, uma interrupção na rede pode deixar o grupo dividido em duas metades, nenhuma das quais é grande o suficiente para manter o cluster em funcionamento.

Mensagens do serviço de escuta não entregues

• Sintoma: O mecanismo de repetição do cluster descarta silenciosamente mensagens não entregues após um período configurado, fazendo com que operações dependentes não sejam executadas.
• Resolução: Para estender a janela de retenção ou evitar a exclusão, edite JITTERBIT_HOME/Resources/jitterbit-agent-config.properties e defina agent.sdk_framework.retry.deleteRetryableMessageAfter para um valor mais alto (em minutos). Para reter todas as mensagens indefinidamente, defina o valor como -1. Reinicie o agente após fazer as alterações.

Registro

Logs de operação de API personalizada não aparecem

• Sintoma: Uma operação acionada por uma API personalizada é executada sem erros, mas nenhuma entrada de log aparece no Studio ou na página Runtime do Console de Gerenciamento.
• Causa: Quando uma API personalizada aciona uma operação, os logs da operação são gerados apenas quando a operação não é bem-sucedida. Operações de API personalizadas bem-sucedidas não produzem entrada de log por padrão.
• Resolução: Para capturar logs para operações de API personalizadas bem-sucedidas, ative o registro de depuração de operações para a operação. Observe que o API Manager possui sua própria visualização de registro separada para solicitações de API.

O registro de depuração da operação para antes da data final selecionada

• Sintoma: O registro de depuração da operação foi ativado com uma data de término futura, mas os logs param de ser gerados antes que essa data seja alcançada.
• Causa: Em grupos de agentes na nuvem, a data de término da configuração de registro de depuração da operação é não confiável. Os logs podem parar de ser gerados antes que o período de tempo configurado termine.
• Resolução: Reative o registro de depuração da operação conforme necessário.

Arquivos de log de depuração da operação sem dados .input ou .output

• Sintoma: Em um agente privado, uma operação tem registro de depuração da operação ativado com dados de entrada e saída de componente ativados. A pasta de log de depuração em DataInterchange/Temp/Debug contém os arquivos .jtr para cada etapa, mas os arquivos de dados correspondentes .input e .output estão ausentes.

• Possíveis causas:

  • O serviço de limpeza do agente está excluindo arquivos .input e .output antes que possam ser revisados.
  • O agente reiniciou enquanto a operação ainda estava em execução, então os arquivos nunca foram escritos até a conclusão. Veja Dados de entrada/saída do componente não gerados para esse cenário.

• Resolução:

  1. No host do agente, abra CleanupRules.xml no diretório de instalação do agente.

  2. Encontre a regra de limpeza para o diretório DataInterchange/Temp/Debug e aumente o valor de <FileAge NumDays = "2"...> para uma janela de retenção mais longa (por exemplo, 7).

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

  3. Reinicie os serviços do agente.

Dados de entrada/saída do componente não gerados

• Sintoma: O registro de depuração da operação está ativado com a geração de dados de entrada e saída de componente ativada, mas nenhum arquivo de dados de entrada/saída aparece para operações de agente privado.

• Resolução: Verifique o log do serviço Verbose Log Shipper no agente:

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

Se o log mostrar erros, reinicie o serviço Verbose Log Shipper. No Linux, isso pode ser feito sem reiniciar todo o agente:

jitterbit stop verboselogshipper
jitterbit start verboselogshipper

No Windows e no Linux, reiniciar todos os serviços do agente Jitterbit também reinicia o serviço Verbose Log Shipper.