Solução de problemas do agente privado Jitterbit

Esta página fornece orientação para solucionar problemas comuns encontrados ao instalar, executar ou gerenciar um agente privado Jitterbit. Comece com as etapas de diagnóstico abaixo e 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 problemas de integração, automação, gerenciamento de API, EDI e desenvolvimento de aplicativos em um único lugar, consulte o guia de solução de problemas do Harmony.

• Observabilidade

  -   [Observabilidade nativa não mostrando dados](#observability-no-data)
  -   [Métricas do agente ausentes quando o agente se conecta através de um proxy HTTP](#metrics-proxy)
  -   [Agente Datadog falha ao iniciar após instalação do Docker](#datadog-docker)
  

  • Problemas de sistema e SO

    • Erro do Apache Server: ConfigArgs não instalado
    • Apache/Tomcat: APPARENT DEADLOCK
    • Apache falha inesperadamente sob carga concorrente
    • Serviço de limpeza não consegue remover arquivos de log bloqueados no Windows
    • Linux: Serviços do agente falham ao iniciar após reinicialização ("postmaster.pid não existe")
    • Linux: Antivírus remove PgBouncer, agente falha ao autenticar no banco de dados incluído
    • Verificações de segurança sinalizam log4j-over-slf4j.jar como vulnerabilidade do Log4j 1.x

  • Docker

    • Geral
    • Agente falha ao reiniciar com erros de autenticação após cancelamento de registro

  • Serviço de escuta

    • "Cluster não atingiu o tamanho mínimo necessário"
    • Mensagens do serviço de escuta não entregues

  • Logging

    • Logs de operação de API personalizada não aparecem
    • Logging de depuração de operação para antes da data de término selecionada
    • Arquivos de log de depuração de operação sem dados .input ou .output
    • Dados de entrada/saída do componente não gerados

Etapas de diagnóstico

Essas etapas são o ponto de partida recomendado para a maioria dos problemas de agentes privados.

Verificar o status do agente

Revise o status atual do agente no Console de Gerenciamento em Agentes > Privado, depois use-o para estreitar o problema. Para as definições de status completas e como elas fazem a transição, consulte Status do agente.

Verificar os arquivos de log do agente

Os arquivos de log do agente são a fonte primária de informações de diagnóstico. Verifique o arquivo a seguir para erros relacionados a conectividade, integridade 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.

Usar 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, Apache e serviços Tomcat.
• service-status: Exibe 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 com todos os arquivos de log do agente, útil ao escalar para o suporte 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

Reiniciar o agente

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

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

Status e conectividade do agente

Agente offline ou inacessível

• Sintoma: A aba Private da página Agents do Management Console mostra o agente como Unknown ou Stopped, ou o Studio exibe um erro Agent Not Running or Unreachable.

• Possíveis causas:

  • Os serviços Jitterbit não estão em execução.
  • Os serviços estão em execução, mas o host do agente não consegue alcançar a nuvem Harmony.
  • Um proxy corporativo está impedindo o agente de se conectar.

• Resolução:

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

    • Windows: Consulte Iniciar um agente Windows.
    • Linux: Consulte Iniciar um agente Linux.

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

    • Windows: C:\Program Files (x86)\Jitterbit Agent\log e o log Event Viewer Application do Windows.
    • Linux: /opt/jitterbit/log.

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

  • Se os serviços estão em execução, mas não conseguem alcançar 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 consegue alcançar o portal Harmony na porta 443.

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

  • Se os serviços do agente estão saudáveis no host (jitterbit status mostra todos os serviços em execução), mas o agente muda repetidamente para Unknown, ou alterna entre Running, Unknown e Stopped, a conexão ou processo do agente provavelmente está sendo interrompido entre heartbeats. Verifique as seguintes possíveis causas:

    • 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 heartbeats. Tente reduzir o intervalo de heartbeat do agente (agent.heart.beat.interval). Para agentes hospedados na nuvem, consulte Azure VM: Conexões perdidas e erros WebSocket/I/O, que também se aplica a outras redes restritas, como AWS.
    • O agente pode ter falhado sob pressão de memória. Verifique se há OutOfMemoryError ou arquivos de despejo de falha hs_err_pid. Consulte Espaço de heap Java: OutOfMemoryError.
    • Se os agentes foram migrados recentemente para um novo sistema operacional enquanto reutilizavam um grupo de agentes que anteriormente hospedava agentes no SO antigo, o grupo reutilizado pode ser a causa. Consulte Agente mostra Unknown ou Stopped após reutilizar um grupo de agentes entre sistemas operacionais.

Agente exibindo versões ou endereços IP diferentes

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

Agente exibindo Desconhecido ou Interrompido após reutilizar um grupo de agentes em sistemas operacionais diferentes

• Sintoma: Após migrar agentes privados para um sistema operacional diferente (por exemplo, Windows para Linux) enquanto reutiliza o mesmo grupo de agentes, os agentes migrados exibem intermitentemente como Desconhecido ou Interrompido na aba Privado da página Agentes do Console de Gerenciamento, mesmo que jitterbit status mostre os serviços em execução e as operações funcionando normalmente.
• Possível causa: Reutilizar um grupo de agentes do sistema operacional anterior pode deixar metadados que interferem na geração de relatórios de status para os novos agentes. O efeito é tipicamente cosmético: serviços e operações continuam funcionando 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 registre os agentes lá.

Falha de sincronização do agente: alterações de projeto não sendo 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.

• Possíveis causas:

  • A implantação usou Implantação Configurável, que implanta apenas os workflows e operações selecionados. Qualquer parte do projeto fora dessa seleção permanece em sua versão implantada anteriormente no agente.
  • O componente não é usado no fluxo lógico de um workflow 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.
  • Ocorreu um timeout de rede ou erro de autorização durante a sincronização.
  • Espaço em disco baixo no host do agente impediu que os arquivos de projeto sincronizados fossem gravados.

• Resolução:

  • Implante novamente 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 workflows ou operações selecionados.
  • Reinicie os serviços do agente para forçar uma sincronização atualizada de todos os projetos implantados.
  • Revise os logs do agente para timeouts de rede relacionados à sincronização ou erros de autorizaçã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. Consulte Espaço em disco e acúmulo de logs.

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

• Sintoma: Após implantar um projeto no Studio, as operações acionadas não iniciam imediatamente, ou aparece um breve acúmulo de operações enfileiradas.
• Causa: O ambiente fica 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 duram, procure por environment-deploy em jitterbit-agent.log. 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, consulte 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 Jitterbit.

Agente exibindo como incapaz

• Sintoma: As operações enviadas ao grupo de agentes são repetidas 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:

  • Todos os threads de trabalho no mecanismo de processamento do agente já estão em uso, portanto o agente não pode aceitar outra operação até que um thread seja liberado. O tamanho do pool é definido por MaxNumberOfWorkerThreads na seção [ProcessEngine] de jitterbit.conf.
  • Uma métrica de capacidade opcional está ativada 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] de 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 ativadas. O Apache atende apenas solicitações de API, portanto o uso de threads do Apache é relevante apenas em um agente que manipula 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 para longas sequências de mudanças de status de capacidade para confirmar que o agente está alternando entre estados capaz e incapaz, depois investigue o seguinte:

  • Se muitas operações são executadas consistentemente ao mesmo tempo, revise MaxNumberOfWorkerThreads na seção [ProcessEngine] de 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 ativadas na seção [AgentCapability]. Se nenhuma estiver ativada, 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 ativado, verifique-o antes das métricas de thread: qualquer um deles ultrapassando 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 ativada, revise os gráficos System Resource Capability, Apache Threads e Tomcat Threads na aba Métricas da página Agentes do Console de Gerenciamento. Ao revisar gráficos de um grupo com múltiplos agentes, use valores de pico ou máximo em vez de médias, pois as médias podem mascarar um único agente sobrecarregado enquanto o resto do grupo parece saudável.
  • Se o grupo de agentes contém 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 apresentou erro. Se apenas um agente estava incapaz, a operação deveria ter sido roteada para um agente capaz. Verifique se o balanceamento de carga está configurado corretamente para o grupo.
  • Se os limites de recursos forem consistentemente atingidos, adicione agentes ao grupo para distribuir a carga.
  • Se a pressão de memória for o gatilho, consulte Espaço de heap Java: OutOfMemoryError.

Falha na transformação: "Failed to find file in the local file store"

• Sintoma: Uma operação falha durante uma transformação com um erro indicando que um arquivo está faltando no armazenamento de arquivos local 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]
  

• Possível causa: Os metadados de implantação de um arquivo não sincronizaram completamente da nuvem Harmony para o agente, portanto o agente não consegue localizar o arquivo em tempo de execução. Geralmente é transitório (por exemplo, uma breve interrupção de sincronização), mas também pode ocorrer após exportar e reimportar um projeto entre ambientes.

• Resolução:
  1. Execute a operação novamente. Na versão 11.38 do agente e posteriores, o agente se auto-recupera dessa 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 de ambiente (a próxima execução de 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 exista um problema mais profundo, como um ambiente que atingiu seu limite de registros de implantação ou uma regressão específica da versão. Entre em contato com o suporte Jitterbit com o nome da operação que está falhando e o 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 no meio do processo, com um destes erros do Windows Installer:

  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 do 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 agrupado do 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 agrupado e o serviço Windows jitterbitpostgres podem não ser totalmente criados. A mensagem pode nomear uma ação diferente, como InstallVerboseLogShipper.

• Possíveis causas:

  • Um Microsoft Visual C++ Redistributable ausente ou conflitante (o PostgreSQL agrupado o requer).
  • Caracteres proibidos na senha do PostgreSQL.
  • Em uma reinstalação, componentes PostgreSQL restantes de um agente anterior. O desinstalador do agente não remove o PostgreSQL, o usuário Windows jitterbitpostgres ou suas entradas de registro por design, e esses resíduos 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 restantes do verbose log shipper de um agente anterior. Como com o PostgreSQL, uma desinstalação padrão não remove o serviço verbose log shipper ou seus arquivos, e esses resíduos podem fazer com que a ação InstallVerboseLogShipper do instalador falhe.
  • Em uma atualização de uma instalação avançada anterior em que o PostgreSQL foi configurado para ser executado em uma conta de serviço Windows diferente de jitterbitpostgres (por exemplo, NT AUTHORITY\NetworkService), a atualização pode falhar com o Erro 1720 em versões do agente anteriores à 12.10.

• Resolução:

  • Instale o Microsoft Visual C++ Redistributable de 64 bits para Visual Studio usando vc_redist.x64.exe (cobre 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, altere a senha para uma válida antes de tentar novamente a instalação.

    Nota

    Em 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 de o PostgreSQL ser instalado.

  • Se 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, o programa PostgreSQL e os diretórios de dados, e as chaves de registro do PostgreSQL foram removidos.

  • Se a mensagem de Erro 1722 nomear 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 anterior for uma instalação avançada com PostgreSQL em execução em uma conta de serviço diferente de jitterbitpostgres, atualize para a versão 12.10 do agente ou posterior, o que resolve isso. Em uma versão anterior do agente, reconfigure o serviço PostgreSQL existente para ser executado na conta de serviço do Windows jitterbitpostgres antes de atualizar.

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

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

• Sintoma: Após uma falha na atualização de um 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 agente privado anteriores a 11.59 / 12.3 quando uma senha incorreta é inserida durante a atualização e o instalador falha em reverter corretamente. Esse problema foi resolvido no agente privado 11.59 / 12.3 e posteriores, onde uma senha incorreta bloqueia a atualização no mesmo diálogo e permite reinserção ou cancelamento sem afetar a instalação existente.

• Resolução:

  1. Abra um prompt de comando como administrador.

  2. Registre novamente 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 sua versão do PostgreSQL. Para encontrá-lo, consulte Versão do PostgreSQL incluída no agente privado.

  3. Inicie os serviços 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. Quando o agente estiver em execução, redefina as senhas do administrador do PostgreSQL e da conta de serviço antes de tentar novamente a atualização.

Falha ao iniciar os serviços do agente após reiniciar o Windows após uma atualização

• Sintoma: Uma atualização de agente privado do Windows de um agente 11.x para um agente 12.x anterior a 12.10 é concluída com sucesso, mas os serviços do Jitterbit Agent falham ao iniciar na próxima vez que o sistema host é reiniciado.

• Possível causa: A atualização deixa o serviço PostgreSQL anterior do Windows (postgresql-x64-<VERSION>, onde <VERSION> é a versão instalada pelo agente anterior) com seu tipo de inicialização ainda definido como Automático. Na reinicialização, esse serviço mais antigo inicia antes do serviço PostgreSQL instalado pela atualização e ocupa a mesma porta, impedindo que o novo serviço PostgreSQL e, portanto, o agente, iniciem.

• Resolução:

  • Atualize para a versão 12.10 do agente ou posterior, que remove o serviço PostgreSQL anterior durante a atualização.
  • Em uma versão anterior do agente, após atualizar, abra Serviços do Windows, identifique o serviço postgresql-x64-<VERSION> mais antigo (aquele anterior à atualização) e defina seu tipo de inicialização como Manual ou Desabilitado, ou desinstale-o, antes de reiniciar o sistema host. Para verificar qual versão está atualmente incluída no agente, execute o comando em Mesma versão que a incluída.

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á habilitada na organização.
• Resolução: Desabilite temporariamente a TFA, instale o agente e reabilite 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 na página Organizações do Console de Gerenciamento.

Recuperar uma instalação do Windows com falha

• 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 depois reinstale o software do agente.

Falha na instalação do Linux sem privilégios de root

• Sintoma: O instalador Linux Redhat Sem Root (x64) falha.

• Resolução: Verifique o seguinte:

  • O usuário sem privilégios de root possui privilégios de sudo. Um administrador do sistema deve adicionar o usuário ao grupo wheel. Para verificar a associação ao grupo atual, execute groups.

  • Quando conectado como o 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 é definido por $HOME/.bashrc.d/jitterbit quando as instruções de instalação são seguidas. Para defini-lo manualmente, execute:

    . /opt/jitterbit/scripts/set.env
    

  • Se o instalador falhar com um erro OPENSSL_3.4.0, esse é um problema conhecido no RHEL 9.7 e posterior. Consulte A instalação do agente privado sem root do RHEL 9.7 e posterior mostra um erro de OpenSSL nos problemas conhecidos do agente privado para uma solução alternativa.

Driver JDBC: "Nenhum driver adequado encontrado"

• Sintoma: Uma conexão de banco de dados falha porque o driver JDBC necessário não está instalado no agente, com um erro como No suitable driver found for 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 arquivo .jar do driver para JITTERBIT_HOME/tomcat/drivers/lib/, depois reinicie o agente. Para as etapas completas, consulte Instalar um driver JDBC.

Conector não baixado para o agent

• Sintoma: Operações falham com erros indicando que um conector está indisponível ou não foi encontrado no agent, normalmente após o lançamento de uma nova versão do conector ou após implantar um projeto que usa um conector que o agent ainda não baixou:

  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 exigida pelo projeto ainda não foi baixada da nuvem para o agent. Geralmente é transitório e se resolve em alguns minutos.
  • Para agents privados: o agent não consegue alcançar a nuvem Harmony para baixar o conector.

• Resolução:

  • No Studio, abra a conexão afetada e clique em Test. Isso faz com que o agent baixe a versão mais recente do conector da nuvem.
  • Se o conector ainda não for baixado, verifique se a política de organização Disable Auto Connector Update está ativada. Quando ativada, o botão Test não baixa versões do conector. Consulte Agent Management.
  • Para baixar o conector sem alterar a política, acesse a página Agents do Management Console, selecione o grupo de agents e escolha Action > Update connectors. Isso força uma atualização do conector no grupo e não é afetado pela política Disable Auto Connector Update.
  • Para agents privados, verifique se o host do agent consegue alcançar a nuvem Harmony. Consulte Agent offline or unreachable.

A instalação do agent não consegue se registrar através de um proxy corporativo

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

  Could not connect to Jitterbit Harmony cloud
  

• Possíveis causas:

  • O proxy está bloqueando a conexão do agent com a nuvem Harmony durante o registro.
  • O proxy requer autenticação que a configuração de proxy do agent não fornece. Os agents privados suportam autenticação de proxy, incluindo um domínio NTLM. Consulte Proxy server for Jitterbit private agents.

• Resolução:

  1. Configure o proxy durante a configuração do agent para que o instalador consiga alcançar a nuvem Harmony através dele, fornecendo as credenciais do proxy (e domínio NTLM, se o proxy exigir). Consulte Configure a proxy during agent setup.
  2. Se o registro ainda falhar através do proxy, peça ao seu time de rede para permitir os domínios e endereços IP do Jitterbit através do proxy ou contorná-lo. As URLs Harmony específicas da região estão documentadas em Allowlist information.
  3. Execute o instalador novamente após o proxy estar configurado ou o host conseguir alcançar 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 de heap Java (-Xmx) do agente privado é muito pequeno para a carga de trabalho (arquivos grandes ou alta concorrência de jobs).

• Resolução:
  1. Aumentar o heap Java máximo do agente privado. Consulte Memória de heap do Tomcat para saber como alterar o valor -Xmx (por exemplo, de -Xmx1024m para -Xmx4096m).
  2. Reiniciar os serviços do agente após fazer a alteração.
  3. Para operações que processam arquivos grandes, configurar chunking para reduzir o uso de memória por job. O Studio aplica transformações de streaming automaticamente quando se qualificam.
  4. Se a observabilidade nativa estiver ativada, usar o gráfico System Resource Capability 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 adequadamente o heap para a carga de trabalho.

Espaço em disco e acúmulo de logs

• Sintoma: O host do agente privado fica sem espaço em disco, o que pode fazer o PostgreSQL desligar ou operações falharem com erros de permissões. Arquivos de log e temporários acumulam nos diretórios do agente, especialmente em agentes que processam altos volumes.
• Resolução:
  • Verificar o espaço em disco disponível no host do agente.
  • Identificar 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. Consulte 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 com falha se repetindo em ProcessEngine.log). Limpar arquivos superdimensionados se o espaço estiver criticamente baixo; limpar o arquivo e reiniciar o agente também pode parar o erro subjacente.
  • Confirmar que o serviço de limpeza está em execução e sua retenção é respeitada. Na seção [FileCleanup] de jitterbit.conf, verificar se AutoStart é true e revisar FrequencyInHours. A retenção por diretório é definida em CleanupRules.xml usando NumDays ou NumOfHours.
  • Se o serviço de limpeza não conseguir excluir arquivos de log ativos (o Tomcat mantém seus logs stdout e stderr abertos no Windows), aumentar o FileAge para esse diretório em CleanupRules.xml para pelo menos um dia, de modo que a limpeza não tenha como alvo arquivos que ainda estão sendo gravados.
  • Se arquivos .dmp de despejo de falha grandes estão consumindo o disco, consulte Arquivos de mini-dump da 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 operações falham com erros como Tomcat service is not running. Se jitterbit status mostra todos os serviços saudáveis no host, mas o status exibido apenas oscila entre Running, Unknown e Stopped, trata-se de um problema de conectividade em vez de um loop de falha. Consulte Agente offline ou inacessível.

• Possíveis causas:

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

• Resolução:

  • Confirme se trata-se de um verdadeiro loop de reinicialização. Verifique os logs do Tomcat em JITTERBIT_HOME/tomcat/logs/ e ProcessEngine.log para a exceção registrada em cada reinicialização. Uma java.net.BindException: Address already in use indica que um processo órfão está ocupando a porta.
  • Interrompa o agente e finalize todos os processos Jitterbit restantes antes de reiniciá-lo. Com o agente parado, procure por processos órfãos: no Linux, execute ps aux | grep -E 'tomcat|jitterbit' e use kill em qualquer ID de processo restante; no Windows, finalize qualquer processo Jitterbit ou Tomcat restante no Gerenciador de Tarefas. Inicie o agente novamente quando nenhum permanecer.
  • 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 está ficando sem memória, aumente a memória disponível (ou o limite de memória do contêiner). Consulte 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 podem causar falha nos serviços em cada reinicialização. Consulte Espaço em disco e acúmulo de logs.
  • Se os logs mostrarem que o Process Engine está falhando em uma operação específica, entre em contato com o suporte Jitterbit com os detalhes da operação e os logs do agente.
  • Se a observabilidade nativa estiver ativada, abra a aba Métricas da página Agentes do Console de Gerenciamento e revise os gráficos de serviço do Tomcat e Process Engine para identificar quando os serviços começaram a falhar.

Operações com timeout ou ignorando configurações de timeout

• Sintoma: Operações são executadas indefinidamente ou por mais tempo que o esperado. Para operações acionadas por API, as configurações de timeout definidas no Studio parecem não ter efeito, e as operações podem permanecer travadas em um status Em execução.

• Possíveis causas:

  • Por padrão, operações acionadas por APIs do API Manager ignoram as configurações de timeout de operação do Studio. A configuração EnableAPITimeout em jitterbit.conf deve ser explicitamente ativada para que operações de API respeitem os valores de timeout.
  • Nenhum tempo máximo de execução de 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 timeout de operação para operações acionadas por API, defina EnableAPITimeout=true na seção [Settings] de jitterbit.conf.
  2. Para limitar o tempo total de execução de qualquer operação, defina MaxOperationRuntimeSeconds na seção [ProcessEngine] de jitterbit.conf. Isso requer que RunOperationsInSeparateProcess seja true (o padrão).
  3. Reinicie os serviços do agente após fazer alterações em jitterbit.conf.

Taxa de transferência do agente inalterada após aumentar max.concurrent.requests

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

• Possíveis causas:

  • Apenas max.concurrent.requests foi alterado. A taxa de transferência do agente também depende dos pools de threads do Tomcat e Apache e dos pools de conexão HTTP, portanto aumentar apenas essa configuração sem dimensionar as outras em conjunto não produz ganho.
  • O host do agente não possui CPU ou memória suficiente para a concorrência adicionada, 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, dimensionando as configurações de pool de threads e pool de conexão relacionadas em conjunto. Consulte Desempenho e ajuste do agente.
  • Confirme que o host do agente possui CPU e memória adequados para a concorrência mais alta. Se o agente falhar ou entrar em um estado incapaz sob carga, consulte Loop de reinicialização do serviço do agente e Espaço de heap Java: OutOfMemoryError.

Desaceleração na transformação XML após atualizar 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 desaceleraçã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.
• Possível causa: A biblioteca de análise XML usada pelo agente foi atualizada na versão 11.45, e a versão atualizada analisa dados XML grandes mais lentamente. Isso afeta transformações que iteram sobre um grande array, porque o mapeamento atravessa repetidamente os dados analisados.
• Resolução:
  • Revise os caminhos de mapeamento da transformação quanto à notação #. Se um caminho usa # para iterar sobre um array, mas apenas o primeiro elemento é necessário, remova o # e reimplante. Remover # mapeia apenas o primeiro elemento, portanto aplique isso apenas quando não for necessário iterar sobre o array completo.
  • 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 atravesse 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 (mini-dumps .dmp e .mdmp, e arquivos hs_err_pid*.log) em <JITTERBIT_HOME>/Tomcat/temp (ou, em compilações mais antigas, a 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.

• Possíveis causas:

  • O coletor de estatísticas de disco AgentStats do agente falha na JVM ao coletar 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, 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 desabilitar 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 então ser deletados com segurança para liberar 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 Jitterbit para uma solução alternativa.

Problemas de banco de dados

Falhas de conexão TranDb

• Sintoma: Operações falham com erros referenciando o banco de dados PostgreSQL interno do agente privado, ou serviços internos do agente falham ao iniciar porque seu limite de conexão foi atingido. Falhas repetidas também podem preencher ProcessEngine.log, aumentando-o 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
  

• Possíveis causas:

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

• Resolução:

  • Versões recentes do agent incluem limites de conexão PostgreSQL e PgBouncer mais altos por padrão, então primeiro confirme que o agent está em uma versão atual. Se um agent atual ainda esgotar seu limite de conexão, entre em contato com o suporte Jitterbit para aumentá-lo sob orientação de suporte. As instâncias PostgreSQL e PgBouncer agrupadas 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 agent e qualquer lentidão de rede ou endpoint upstream que esteja acumulando operações.
  • Em um agent Windows, desabilite o IP Helper. Consulte Problema IPv6 no Windows.

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

• Sintoma: você deseja alterar o método de autenticação PostgreSQL agrupado em um agent privado Linux de MD5 para SCRAM-SHA-256, mas o agent continua usando MD5.

• Possíveis causas:

  • MD5 é a criptografia de senha padrão para o PostgreSQL agrupado em agents privados Linux. SCRAM-SHA-256 era 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 agent Linux da versão 12.6 ou 12.7, o instalador solicita que você redefina a criptografia para MD5 ou mantenha SCRAM-SHA-256; consulte Atualizar um agent Linux.
  • Editar apenas pg_hba.conf e postgresql.conf não completa a mudança. O PgBouncer também deve ser reconfigurado com o hash do verificador SCRAM, ou o agent falha ao iniciar.

• Resolução: para alternar um agent 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 oferece melhor desempenho, portanto a mudança é intencional e envolve várias etapas: o guia reconfigura o PostgreSQL agrupado, atualiza as senhas do usuário e reconfigura o PgBouncer com o novo hash. Reconfigurar a instância agrupada é a forma suportada de ativar SCRAM. Não substitua a instância agrupada pela sua própria instância PostgreSQL para obter SCRAM: agents que usam uma instância PostgreSQL diferente da agrupada não são suportados.

PostgreSQL: Encerramento rápido administrativo

• Sintoma: todas as operações falham porque o banco de dados do agent está indisponível (as operações podem ficar travadas em um status Pendente), e o log do PostgreSQL registra um encerramento 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 tarefa agendada, ou uma ferramenta de monitoramento ou backup que reinicia serviços.
  • O host do agent ficou com pouca CPU ou memória, causando a falha do Tomcat e levando o PostgreSQL com ele.

• Resolução:

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

Rede e conectividade

Falha no handshake de certificado (TLS)

• Sintoma: Operações que se conectam a endpoints seguros falham durante o handshake 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 endpoint usa renegociação TLS legada, que o agente bloqueia por padrão.
  • O agente e o endpoint não conseguem negociar uma versão TLS ou cifra comum. Os agentes da versão 11.x e 12.x usam bibliotecas de segurança diferentes, portanto um endpoint que falha ao conectar em um agente 11.x pode ter sucesso em um agente 12.x.
  • O certificado do endpoint (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: No host do agente, execute o seguinte para confirmar qual versão TLS o endpoint negocia e se o handshake é bem-sucedido no nível de 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] de jitterbit.conf e reinicie o agente. Esta configuração requer agente versão 11.39 ou posterior.
  • 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), depois 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. Consulte SQL Server: Conexão falha com erro de caminho de certificado PKIX.
  • Se uma falha de negociação TLS ou handshake 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 certificado atualizado.

Conexão com sandbox do Salesforce falha com incompatibilidade de certificado

• Sintoma: Uma conexão de agente privado a um endpoint que requer Server Name Indication (SNI) falha com 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:

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

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

• Causa: O handshake TLS não está incluindo a extensão SNI, portanto o servidor retorna um certificado padrão em vez daquele para o 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. SNI é enviado por padrão, portanto quando está ausente, algo está suprimindo ou removendo-o.

• Resolução:

  1. Confirme que SNI é a causa. No host do agente, compare o certificado retornado com e sem SNI:

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

Se o primeiro retorna o certificado correto e o segundo retorna o incompatível, SNI é a causa.

1. Verifique se SNI está explicitamente desabilitado 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 SNI). Reinicie os serviços do agente.
2. Se 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 de um grupo de agentes na nuvem, SNI não é a causa. O certificado do servidor pode não listar o host em seus Nomes Alternativos do Assunto. Para Salesforce, adicione a URL do MyDomain da sandbox ao certificado Salesforce ou consulte Incompatibilidade de Nome Alternativo do Assunto (SAN) do Certificado.

FTP: Tempo limite da conexão de dados excedido

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

• Possíveis causas:

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

• Resolução:

  • Nas configurações de conexão FTP, alterne 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 no nível de conexão, ative o log de depuração curl definindo CurlDebugDir na seção [Settings] de jitterbit.conf. Consulte Logs do Curl.

SSH: Falha na conexão SFTP devido ao caminho do arquivo de chave incorreto

• Sintoma: 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.
• Resolução: Use barras normais em todos os caminhos de arquivo de chave SSH em jitterbit.conf, mesmo no Windows (por exemplo, C:/jitterbit/keys/id_rsa). Consulte [SSH].

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

• Sintoma: 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 reinicialização do agente. As configurações de chave SSH adicionadas ao jitterbit.conf local também podem deixar de funcionar após o agente reiniciar.

  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 remota do agente está habilitada (está por padrão), portanto as configurações gerenciadas através da aba Configuração Jitterbit do Console de Gerenciamento têm precedência. As configurações de chave SSH adicionadas apenas ao jitterbit.conf local podem não funcionar ou podem não ser retidas após o agente reiniciar.
  • As configurações de chave SSH (PrivateKeyFile, PrivateKeyPassphrase, PublicKeyFile) estão na seção incorreta. Versões mais recentes do agente analisam estritamente e ignoram configurações SSH colocadas fora da seção [SSH] (por exemplo, sob [SSL]).

• Resolução:

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

Falha de autenticação SFTP em 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) funcionam, e conectar ao servidor com falha a partir da linha de comando do SO também funciona.

  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 recentes que a biblioteca cURL fornecida em versões mais antigas do agente não suporta. Servidores que ainda aceitam os algoritmos mais antigos continuam funcionando, razão pela qual a mesma chave funciona 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: Falha de autenticação básica através do túnel proxy

• 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 proxy falham com um erro de autenticação.
• Causa: Versões modernas do JDK desabilitam a autenticação básica durante o tunelamento de proxy HTTPS por padrão. A propriedade JVM jdk.http.auth.tunneling.disabledSchemes bloqueia autenticação básica a menos que seja explicitamente removida.
• 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, consulte Permitir autenticação básica durante 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) junto com 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 o alcancem.

• Causa: Agentes privados não requerem que nenhuma porta de entrada seja aberta, 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 para o Harmony sobre HTTPS (porta 443). Todo o tráfego do Harmony e do gateway para o agente é roteado de volta por essa 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 sobre o WebSocket de saída existente. O agente roteia a carga útil de 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 com vários gateways).

• Resolução:

  • Abra HTTPS de saída (porta 443) do host do agente para as 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, coloque na 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. Consulte Portas de rede.
  • Se um gateway de API privado for implantado, também permita conectividade de saída de cada host do agente para o gateway (diretamente ou através de seu balanceador de carga em uma implantação com vários gateways). O agente se conecta ao gateway para retornar o payload da resposta da API. Para o fluxo de solicitação completo, consulte 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 um payload de solicitação ou resposta (cabeçalhos mais corpo, compactado) excede aproximadamente 1 KB, o gateway de API em nuvem Jitterbit prepara o payload, e o agente privado faz uma conexão de saída para o host jitterbitsysservice de sua região para baixar o payload da solicitação (ou fazer upload do payload da resposta) antes de concluir a operação. Se o host do agente não conseguir alcançar 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 de conexão do agente padrão 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 de 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. Consulte Informações de lista de permissões Jitterbit para as URLs e IPs específicos da região.
  2. Verifique a conectividade executando um teste HTTP do host do agente para a URL jitterbitsysservice de sua região e confirme que a API não expira mais.

Problema de IPv6 no Windows

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

• Resolução: Desative IPv6 e 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 de seleção 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 e defina Tipo de inicialização como Desativado:

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

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

Conexões perdidas

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

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

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

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

   #Agent heart beat interval (IN MINUTES)
   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 de inatividade do IP da VM do Azure, o tempo limite de inatividade TCP do gateway NAT e o tempo limite de fluxo da rede virtual (VNET) para 15 minutos cada. Isso é abordado nas etapas a seguir.

Identificar erros relevantes

Verifique os logs de operação e jitterbit-agent.log para as seguintes mensagens.

Erros do log de operação:

The operation "Example Operation" completed successfully.

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

Run message could not reach the agent.

Erros do log do agente:

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

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

Parar o agente com drenagem

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

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 de inatividade 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 Configuration e defina Idle timeout (minutes) como 15:

   

Atualizar o tempo limite de inatividade 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 de inatividade TCP (minutos) como 15.

Atualizar o tempo limite de fluxo da VNET

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

2. Clique no item da 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) como 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

Observabilidade nativa não mostrando dados

• Sintoma: Após ativar 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 aguardar vários minutos.

• Possíveis causas:

  • 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 de configuração.
  • O host do agente não consegue alcançar a nuvem Harmony, impedindo que as métricas sejam enviadas.
  • Antes da versão 12.10 do agente, atualizar um agente privado do Windows cuja porta do PgBouncer já era 6434 (consulte Portas do PgBouncer) não atualizava a conexão do serviço de métricas para corresponder, então permanecia na porta antiga 6432 e a métrica do PGBouncer poderia relatar incorretamente.
  • Antes da versão 12.9 do agente, instalar um agente privado como usuário não-root no Linux não provisionava o PgBouncer, então o serviço nunca iniciava e seu status sempre mostra como não íntegro.

• Resolução:

  • Verifique se jitterbit.conf contém todas as configurações necessárias das seções [AgentMetrics] e [AgentCapability]. Consulte o exemplo de configuração completo 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 de configuração foi feita.
  • Verifique se o host do agente consegue alcançar a nuvem Harmony. Consulte Agente offline ou inacessível. Se o agente se conecta através de um proxy, consulte Métricas do agente ausentes quando o agente se conecta através de um proxy HTTP.
  • Para um agente afetado pela incompatibilidade de porta, atualize para a versão 12.10 ou posterior do agente, que corrige automaticamente a porta de conexão do PgBouncer do serviço de métricas. Se a incompatibilidade persistir após a atualização, entre em contato com o suporte Jitterbit para verificar a porta.
  • Para um novo agente privado do Linux não-root, use a versão 12.9 ou posterior, onde o PgBouncer é provisionado corretamente 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 por HTTPS usando uma conexão separada que não herda a configuração de 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 se conecte com sucesso.
• Resolução:
  1. Confirme que o proxy suporta HTTPS. As métricas do agente são enviadas por HTTPS, portanto um proxy que manipula apenas tráfego HTTP as bloqueia. Ativar HTTPS no proxy resolve o problema.
  2. Se não conseguir ativar HTTPS no proxy, ou se as métricas ainda estiverem faltando após ativá-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 Jitterbit para configurá-lo.

Falha ao iniciar o agente Datadog após instalação no Docker

• Sintoma: Após instalar o agente Datadog dentro de um contêiner Docker como parte da configuração de observabilidade 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 Apache Server: ConfigArgs não 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 qual o deadlock recorre sob carga.

• Possíveis causas:

  • O pool de conexões de banco de dados do agente sofre 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 timeouts padrão.
  • Processos Jitterbit obsoletos estão retendo 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 interrompidos sem que todos os processos Jitterbit terminem corretamente.
  • O host do agente está sobrecarregado pela atividade de pico, ou sua CPU está sendo limitada. Por exemplo, uma instância de nuvem expansível (como um tipo AWS t3) limita sua CPU uma vez que seus créditos de burst se esgotam, o que pode prejudicar o PostgreSQL interno sob carga.

• Resolução:

  • Interrompa todos os serviços do Jitterbit, finalize todos os processos do Jitterbit ainda em execução e reinicie os serviços para limpar o deadlock.
  • Se o deadlock estiver no pool de conexões Java (c3p0) e o PostgreSQL em si estiver saudável, alterne o agente para seu pool de conexões C++ interno definindo UseInternalPooling=true na seção [DbInfo] de jitterbit.conf e 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 na nuvem, use um tipo de instância com desempenho de CPU sustentado (não expansível).
  • Antes de atualizar um agente, interrompa-o com drenagem e deixe as operações em execução terminarem, para que nenhum processo fique retendo conexões de banco de dados durante a atualização. Em ambientes ocupados, reserve tempo extra para que a interrupção com drenagem seja concluída.

Apache falha inesperadamente sob carga concorrente

• Sintoma: Sob carga concorrente, o processo Apache do agente falha e reinicia inesperadamente, e o agente pode aparecer brevemente como parando ou reiniciando no Console de Gerenciamento. As operações em execução no momento podem falhar ou ficar em estado incompleto.
• Possíveis causas:
  • Um script usa chamadas aninhadas de RunOperation para executar uma operação filha de forma síncrona (o padrão) a partir de uma operação pai, e ambas as operações leem ou escrevem a mesma variável global ao mesmo tempo.
  • Uma transformação está configurada com chunking e múltiplas threads, e uma thread termina a execução antes de outra thread que começou ao mesmo tempo.
  • Múltiplas operações com geração de dados de entrada e saída de componentes habilitada são executadas ao mesmo tempo.
• Resolução: Atualize o agente privado para a versão 12.10 ou posterior, que resolve esses problemas. Nenhuma solução alternativa existe em versões anteriores.

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

• Sintoma: 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.
  

• Possíveis causas:

  • Um processo do agente está mantendo o arquivo aberto. No Windows, o serviço de limpeza não consegue remover um arquivo 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 nos arquivos do 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 quando não estiverem mais em uso. Reinicie o agente após editar o arquivo.
  • Exclua os logs stdout e stderr do Tomcat 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 Agent falham ao iniciar após reinicialização ("postmaster.pid não existe")

• Sintoma: Após reinicializar um host de agent privado Linux, os serviços do agent falham ao iniciar. Executar sudo jitterbit status mostra o scheduler e outros serviços não em execução, e os logs do agent (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 PostgreSQL agrupado são muito permissivas. O PostgreSQL requer que o diretório de dados seja 700 (somente do proprietário). Se as permissões forem mais amplas (por exemplo, 755 ou 777), o PostgreSQL se recusa a iniciar, o que impede que o restante do agent seja iniciado.

• 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 PostgreSQL como 700:

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

  3. Inicie os serviços do agent:

     sudo /etc/init.d/jitterbit start
     

Linux: Antivírus remove PgBouncer, agent falha ao autenticar no banco de dados agrupado

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

  [FATAL] password authentication failed for user "jitterbit"
  

  O log do agent mostra que não consegue se conectar ao banco de dados. A falha persiste em desinstalação e reinstalação completas.

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

• Resolução:

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

  3. Reinstale o agent. No RHEL/CentOS:

     sudo dnf reinstall jitterbit-agent
     

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

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

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

Docker

Geral

Os seguintes pontos se aplicam a problemas relacionados ao Docker:

• Um agent privado Docker não iniciará se o diretório conf contiver um arquivo credentials.txt e um arquivo register.json.

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

Falha ao reiniciar o agente com erros de autenticação após cancelamento de registro

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

• Causa: Quando o agente para com deregisterAgentOnDrainstop=true, ele cancela o registro no 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á ativado cancela automaticamente o registro do agente existente e registra um novo. As etapas abaixo se aplicam a agentes Docker em versões anteriores e a agentes Linux em qualquer versão.

• Resolução: Remova o arquivo credentials.txt obsoleto e reinicie o agente para disparar um novo registro.

  Em um agente Linux não containerizado, 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

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

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

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

• Possíveis causas:

  • Poucos agentes do grupo de agentes estão em execução e ingressados no 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 reingressar, reduzindo o número de agentes em execução e ingressados abaixo do necessário \((N / 2) + 1\).
  • Uma interrupção de rede dividiu o grupo de agentes em vários clusters menores. Por exemplo, em um grupo de 4 agentes, uma divisão de rede pode produzir dois clusters de 2 agentes cada; nenhum atende ao necessário \((N / 2) + 1\) de 3, portanto ambos relatam o erro mesmo que cada agente esteja em execução.

• Resolução:

  • Confirme que \((N / 2) + 1\) dos agentes do 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. Por exemplo, um grupo de 4 agentes requer 3, e um grupo de 5 agentes também requer 3. Para ver quais agentes ingressaram, 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 está inativo e as mensagens permanecem não processadas com persistência ativada, restaure o cluster manualmente. Consulte Restauração de 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 de rede pode deixar o grupo dividido em duas metades, nenhuma das quais é grande o suficiente para manter o cluster em execução.

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, causando a não execução de operações dependentes.
• Resolução: Para estender a janela de retenção ou impedir 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.

Logging

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, logs de operação são gerados apenas quando a operação não é bem-sucedida. Operações de API personalizada bem-sucedidas não produzem entrada de log por padrão.
• Resolução: Para capturar logs de operações de API personalizada bem-sucedidas, ative o logging de depuração de operação para a operação. Observe que o API Manager possui sua própria visualização de logging separada para solicitações de API.

O logging de depuração de operação para antes da data de término selecionada

• Sintoma: O logging de depuração de operação foi ativado com uma data de término futura, mas os logs param de ser gerados antes dessa data ser atingida.
• Causa: Em grupos de agentes na nuvem, a data de término da configuração de logging de depuração de operação é pouco confiável. Os logs podem parar de ser gerados antes do período de tempo configurado terminar.
• Resolução: Reative o logging de depuração de operação conforme necessário.

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

• Sintoma: Em um agente privado, uma operação possui logging de depuração de 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 .input e .output correspondentes estão faltando.

• Possíveis causas:

  • O serviço de limpeza do agente está excluindo arquivos .input e .output antes que possam ser revisados.
  • O agente foi reiniciado enquanto a operação ainda estava em execução, portanto, os arquivos nunca foram gravados completamente. Consulte Dados de entrada/saída de 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. Localize a regra de limpeza para o diretório DataInterchange/Temp/Debug e aumente o valor <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 de componente não gerados

• Sintoma: O logging de depuração de 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 uma reinicialização completa do agente:

  jitterbit stop verboselogshipper
  jitterbit start verboselogshipper
  

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