# Como resolver problemas comuns em 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. ```json { "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"](https://docs.digibee.com/documentation/troubleshooting/pt-br/deployment-issues/pipeline-execution-was-aborted-error). {% code overflow="wrap" %} ```json { "timestamp": 1730438185028, "error": "This pipeline execution was aborted and cannot be automatically retried because it was configured to disallow redeliveries.", "code": 500 } ``` {% endcode %}
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. {% code overflow="wrap" %} ```json { "timestamp": 1734254417051, "error": "java.sql.SQLTransientConnectionException: HikariPool-1 - Connection is not available, request timed out after 60000ms.", "code": 500 } ``` {% endcode %}
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. {% code overflow="wrap" %} ```json { "timestamp": 1734134205495, "error": "An internal error has occurred. Exception: java.lang.NullPointerException: Cannot invoke \"String.length()\" because \"sql\" is null", "code": 500 } ``` {% endcode %}
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. ![](https://content.gitbook.com/content/3ANg0NQQeslB7Og5K7Ah/blobs/Vo74ifxboTTq6GEYisnj/Example%20-%20Unexpected%20restarts.png)
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** {% stepper %} {% step %} **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.
{% endstep %} {% step %} #### 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**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/dashboards/completed-executions). 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.
{% endstep %} {% step %} **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**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/dashboards/completed-executions)**:** Exibe a chave de execução, as mensagens de entrada/saída e os timestamps de início e término. * [**Pipeline Logs**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/dashboards/pipeline-logs)**:** Fornece logs das etapas executadas, desde a solicitação até a resposta do pipeline. {% hint style="warning" %} Nem todos os conectores geram logs automaticamente. Conectores como [**Log**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/log) e conectores de interação externa (por exemplo, [**REST**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/rest-v2), [**Google Storage**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/file-storage/google-storage), [**Stream DB**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/structured-data/stream-db-v3)) sempre registram mensagens. No entanto, os resultados de transformações de dados ou conectores externos só são exibidos se forem registrados explicitamente. {% endhint %} {% endstep %} {% endstepper %} ### **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**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/rest-v2) ou [**SOAP**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/soap-v3). * 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**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/structured-data/object-store) ou no [**Session Management**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/structured-data/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**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/email-v2) e [**Template Transformer**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/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**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/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**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/rest-v2) ou [**SOAP**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/soap-v3)), verifique suas configurações, como os ajustes de tempo limite e a estrutura dos dados enviados ou recebidos. * Você pode usar um [**Assert**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/assert-v2) 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**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/overview/runtime#replicas), [**Execuções simultâneas**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/overview/runtime#execucoes-simultaneas) e alocação de memória ([**Tamanho do pipeline**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/overview/runtime#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](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/dashboards/alerts).
* **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](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/dashboards/monitor-insights-beta).
### **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**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/dashboards/pipeline-logs); ela será exibida com o valor "manual" no campo **Origem**. {% hint style="info" %} 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. {% endhint %} ## **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](https://docs.digibee.com/documentation/troubleshooting/pt-br/help-and-faq/support). 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.