Como resolver problemas comuns em pipelines

Saiba como identificar e resolver erros comuns em seus pipelines.

O que é considerado um erro?

Em integrações, um erro é uma falha ou comportamento inesperado que interrompe o fluxo normal de dados entre sistemas, serviços ou conectores. Esses erros podem ocorrer em qualquer etapa da execução.

Exemplos de erros em integrações

Timeout

Descrição: Ocorre quando o pipeline excede o tempo máximo de execução configurado, forçando a interrupção do processo.

Exemplo: Um pipeline que consulta um banco de dados externo demora mais de 15 minutos para completar a requisição devido ao grande volume de dados.

{
  "timestamp": 1730373482528,
  "error": "Pipeline execution timed-out.",
  "code": 500
}

Out of Memory (OOM)

Descrição: Este erro acontece quando o pipeline consome mais memória ou CPU do que o permitido pela configuração, interrompendo a execução.

Exemplo: Um pipeline processa um arquivo grande ou consulta uma API de alto volume sem paginação, resultando em uso excessivo de memória. Saiba como resolver o erro "Pipeline execution was aborted".

{
  "timestamp": 1730438185028,
  "error": "This pipeline execution was aborted and cannot be automatically retried because it was configured to disallow redeliveries.",
  "code": 500
}

Falhas de conexão

Descrição: Erro de comunicação entre o pipeline e um serviço externo ou banco de dados, como falhas de autenticação ou servidores indisponíveis.

Exemplo: Um pipeline tenta acessar uma API externa, mas encontra um erro de autenticação ou não consegue conectar porque o servidor está temporariamente indisponível.

{
  "timestamp": 1734254417051,
  "error": "java.sql.SQLTransientConnectionException: HikariPool-1 - Connection is not available, request timed out after 60000ms.",
  "code": 500
}

Erros de configuração

Descrição: Erros causados por configurações incorretas, como endpoints inválidos, parâmetros ausentes ou limites de tamanho incorretos.

Exemplo: Um pipeline com um endpoint incorreto para uma API REST não consegue enviar dados, resultando em erro de URL inválida.

{
    "timestamp": 1734134205495,
    "error": "An internal error has occurred. Exception: java.lang.NullPointerException: Cannot invoke \"String.length()\" because \"sql\" is null",
    "code": 500
}

Reinicializações inesperadas

Descrição: Quando a infraestrutura de integração, como os containers do pipeline, é reiniciada devido a problemas internos, como erros de OOM.

Exemplo: Um pipeline que consome muita memória leva a uma reinicialização automática pelo Kubernetes e gera um aviso de “reciclado” na tela de Runtime.

Expiração de mensagens em filas de eventos

Descrição: Mensagens expiram se não forem processadas a tempo, levando à sua eliminação.

Exemplo: Uma mensagem expira antes de ser consumida pelo próximo pipeline, especialmente se o tempo de expiração da fila for curto e a carga de dados for alta.

Guia passo a passo para identificar, analisar e resolver problemas

Identificando o problema

1

Reúna informações iniciais

Certifique-se de ter a chave de execução dos logs de erro ou encontre-a filtrando os logs por tempo e campos relevantes.

2

Acesse o pipeline e a execução

Abra duas abas: uma para o pipeline analisado e outra para a execução associada na página Execuções Concluídas. Isso permite comparar a integração configurada (pipeline) com o que realmente aconteceu (execução).

• Build: Mostra como sua integração está configurada.

• Monitor: Mostra detalhes da execução e possíveis pontos de erro.

3

Analise os logs

Confira os logs de execução para rastrear o caminho da integração, encontrar o ponto onde a integração foi abortada ou identificar o erro. Os logs podem ser analisados individualmente ou em múltiplas execuções. Você pode visualizá-los de duas maneiras:

• Execuções Concluídas: Exibe a chave de execução, as mensagens de entrada/saída e os timestamps de início e término.
• Pipeline Logs: Fornece logs das etapas executadas, desde a solicitação até a resposta do pipeline.

Nem todos os conectores geram logs automaticamente. Conectores como Log e conectores de interação externa (por exemplo, REST, Google Storage, Stream DB) sempre registram mensagens. No entanto, os resultados de transformações de dados ou conectores externos só são exibidos se forem registrados explicitamente.

Analisando o problema

Método 1

Compare uma integração bem-sucedida com uma integração que falhou. Identifique dados que foram integrados corretamente (por exemplo, um número de pedido) e dados que falharam. Caso dados semelhantes sigam fluxos diferentes, compare os logs para encontrar o ponto de divergência.

Método 2

Identifique padrões nas falhas de execução. Por exemplo, se execuções simultâneas falharem com timeout, analise os logs para determinar qual etapa causou o problema e qual conector ou serviço está associado a ele.

Resolvendo problemas comuns

Timeout

O que é: Um timeout ocorre quando o pipeline excede o tempo de execução, geralmente 15 minutos (900.000 milissegundos).

Como corrigir:

• Aumente o tempo limite no trigger do pipeline, mas evite ultrapassar o limite máximo.

• Identifique onde o timeout ocorre no fluxo. Ajuste o tempo limite no conector para requisições específicas, como REST ou SOAP.
• Reestruture pipelines que estejam próximos do limite de 10 minutos, processando os dados em partes menores com paginação.

Out of Memory (OOM)

O que é: Ocorre quando o pipeline excede o limite de memória configurado.

Como corrigir:

1. Identifique a causa: Use a página Monitor para analisar os logs e determinar onde o erro está ocorrendo. Adicionar logs pode ajudar a refinar a análise.

2. Otimize o fluxo: Implemente paginação para reduzir o volume de dados ou divida o fluxo em pipelines primários e secundários para lógica de enriquecimento e envio de dados.

3. Ajuste a implantação: Após reestruturar o pipeline, teste-o e, em seguida, implante-o em Produção. Se o erro persistir, aumente o tamanho do pipeline e realize uma nova implantação.

Configuração do trigger e expiração da fila

O que é: O trigger do pipeline inicia a execução, e a expiração da fila determina quanto tempo uma mensagem pode aguardar para ser processada.

Como corrigir:

• Para cenários de baixo volume, configure tempos de expiração mais curtos (2-5 minutos) para evitar acúmulo desnecessário de mensagens.

• Para cenários de alto volume, estenda o tempo de expiração para 10-15 minutos, dependendo do tempo necessário para consumir e processar as mensagens.

• Ajuste o tempo de expiração para evitar a perda de mensagens que ocorre quando as filas expiram antes do processamento.

Sugestões:

• Certifique-se de que o trigger está configurado de acordo com a carga esperada antes de executar o pipeline.

• Monitore as filas regularmente para ajustar o tempo de expiração ao volume e ao comportamento esperado do pipeline.

Lentidão no Object Store ou no Session Management

O que é: Lentidão no Object Store ou no Session Management ocorre quando o volume de dados armazenados aumenta significativamente sem uma rotina de limpeza ou exclusão. Isso sobrecarrega o banco de dados, desacelera as consultas e a execução do pipeline, afetando o desempenho geral.

Como corrigir:

• Verifique o volume de dados: Acesse o Object Store e analise o tamanho atual do banco de dados. Se o volume de dados estiver alto, implemente uma rotina de limpeza para melhorar o desempenho.

• Implemente uma rotina de limpeza: Configure uma rotina para remover dados antigos ou desnecessários. Isso evitará o acúmulo excessivo de dados e manterá o armazenamento mais eficiente.

• Divida o processamento em partes menores: Para pipelines que processam grandes volumes de dados, utilize paginação ou divida o fluxo em diferentes pipelines. Um pipeline realiza a primeira consulta e envia os dados para outros pipelines. Isso mantém o Object Store mais limpo e o processo de integração escalável.

• Teste e monitore: Após implementar uma rotina de limpeza ou reestruturar o pipeline, monitore o desempenho em um ambiente de teste. Verifique se o atraso diminuiu e, se necessário, ajuste o processo de limpeza ou o fluxo de integração antes de implantá-lo no ambiente de Produção.

Suporte de ferramentas externas

Algumas vezes, é possível usar ferramentas externas para auxiliar em certos aspectos da integração:

• Validação de certificados SSL: Para verificar se os certificados estão corretamente atualizados e ativos em caso de problemas de conexão.

• Validação e comparação de XML: Para depurar erros em fluxos de trabalho XML e comparar execuções bem-sucedidas com falhas.

• Gerador de HTML: Para criar mensagens HTML utilizadas em conectores como Email e Template Transformer.
• Gerador de esquema JSON: Para gerar esquemas a partir de um arquivo JSON válido.

• Gerador de dados fictícios: Para testar com grandes volumes de dados.

• Ferramentas de IA: Para simplificar soluções lógicas, como a criação de expressões regulares (RegEx).

Aprimorando diagnósticos

Preste atenção nos logs

• Os logs são cruciais para identificar rapidamente onde os erros ocorrem no pipeline. Para diagnósticos eficazes, recomendamos posicionar o conector Log em pontos estratégicos do pipeline. Coloque-o antes e depois de conectores críticos, como transformações de dados, chamadas para serviços externos e decisões de fluxo. Isso permitirá rastrear o caminho exato da execução e identificar problemas específicos.
• Monitore esses logs regularmente para identificar padrões de erro ou sinais de desempenho inadequado. Com o conector Log configurado em áreas-chave, você terá uma visão mais detalhada da execução, facilitando o rastreamento de problemas.

Verifique as configurações do trigger e da fila

• Certifique-se de que o trigger do pipeline está configurado corretamente e que o tempo de expiração da fila é adequado para o volume de dados que está sendo processado. Erros no trigger ou um tempo de expiração muito curto podem levar à perda de mensagens importantes.

• Configure o trigger de acordo com os requisitos do fluxo de dados e ajuste o tempo na fila, se necessário, para garantir que as mensagens tenham tempo suficiente para serem processadas. Fique atento ao tempo de expiração da fila de eventos e verifique regularmente o tempo de vida das mensagens nas filas.

Revise a implementação do pipeline

• Analise cada conector do pipeline para identificar possíveis pontos de falha. Se for detectado um erro em um conector específico (por exemplo, REST ou SOAP), verifique suas configurações, como os ajustes de tempo limite e a estrutura dos dados enviados ou recebidos.
• Você pode usar um Assert para verificar se os dados retornados por serviços externos estão no formato esperado, garantindo uma integração mais robusta.

Monitore as configurações de implantação

• Configurações de implantação, como o número de Réplicas, Execuções simultâneas e alocação de memória (Tamanho do pipeline), têm um impacto significativo no desempenho do pipeline. Certifique-se de que a memória e as réplicas estão dimensionadas adequadamente para a carga de trabalho esperada, especialmente para pipelines de alta demanda.
• Ajuste essas configurações conforme necessário para garantir um desempenho estável e minimizar erros de execução.

Use as ferramentas de monitoramento da Digibee

A Digibee Integration Platform fornece ferramentas de monitoramento e insights para detectar problemas, como aumento nos tempos de resposta ou taxas de erro incomuns. Ative essas ferramentas para monitorar a saúde dos pipelines em tempo real e receber alertas proativos sobre problemas de desempenho ou configuração.

• Configuração de alertas: Nesta página, é possível personalizar notificações de desempenho da integração com base em métricas, permitindo ações rápidas para minimizar impactos operacionais. Saiba mais na documentação de Alertas.

• Monitor Insights: Este recurso oferece insights sobre a saúde das integrações concluídas. Selecionar um insight te direciona às métricas das execuções que exigem atenção, já filtradas pelo período de ocorrência. Mais informações estão disponíveis na documentação do Monitor Insights.

Reprocessar execuções manualmente

• Esse recurso permite aos usuários tentar novamente chamadas processadas anteriormente, sendo útil em cenários onde a chamada original falhou devido a problemas temporários, como interrupções de rede ou erros no sistema de destino.

• O reprocessamento manual exige a identificação da chamada com falha e a verificação dos parâmetros usados anteriormente. Dependendo da configuração, é possível manter os mesmos parâmetros ou alterá-los. Após reprocessar a chamada, realize uma nova pesquisa na página Pipeline logs; ela será exibida com o valor "manual" no campo Origem.

Embora o reprocessamento manual seja uma ferramenta eficaz, deve ser usado com cautela. Em alguns casos, pode ser necessário investigar as causas dos erros antes de simplesmente repetir chamadas, para evitar a repetição dos mesmos erros.

Ainda enfrentando problemas com sua integração?

Se sim, abra um ticket com nossa equipe de Suporte. Veja como abrir um ticket e os prazos esperados.

Ao abrir o ticket, forneça as seguintes informações relevantes:

• Nome do pipeline ou ID de Execução

• Análises prévias realizadas pelo cliente com evidências de testes

• Outras informações pertinentes para auxiliar na identificação e análise

• Comportamento esperado versus comportamento observado

• Mensagem de erro com data e horário

• Chave do pipeline (para erros ou incidentes)

• Ambiente (Produção ou Teste)

• Nome do projeto (se aplicável)

Conclusão

Seguindo as recomendações deste guia, você pode solucionar problemas em pipelines na Digibee Integration Platform de forma mais eficiente e independente. Com uma abordagem organizada e a aplicação de boas práticas — como análise detalhada de logs, monitoramento adequado das filas e ajustes nas configurações de implantação — é possível identificar e resolver rapidamente erros comuns que afetam a execução da integração.

A Digibee Integration Platform oferece ferramentas que, junto com os procedimentos de solução de problemas apresentados, permitem resolver muitos problemas de forma autônoma. Quando necessário, utilize recursos como reprocessamento manual e ferramentas de monitoramento para validar correções e garantir a estabilidade dos pipelines.