# Boas práticas para tratamento de erros em pipelines O tratamento adequado de erros é essencial para garantir a estabilidade, previsibilidade e confiabilidade das integrações construídas na Digibee Integration Platform. Sem uma gestão eficaz de falhas, os pipelines podem apresentar comportamentos inesperados, dificultando a manutenção e impactando processos críticos. Neste artigo, exploramos boas práticas para lidar com erros de forma eficiente. ## **Uso do Fail On Error e OnException** ### **Fail On Error** Essa opção está disponível nas configurações da maioria dos conectores da Plataforma. Quando ativada, a execução do pipeline é interrompida. Em conectores que utilizam [subfluxos](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/build-overview/pipelines/subpipelines), uma exceção é enviada para o fluxo do **OnException**. ### **OnException** O [**OnException**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/build-overview/pipelines/subpipelines#onexception) está presente em alguns conectores com subfluxos, como [**Do While**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/logic/do-while), [**For Each**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/logic/for-each) e [**Retry**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/logic/retry), e desempenha um papel importante na captura de falhas controladas. Ele permite centralizar o tratamento de erros em um ponto do pipeline, facilitando ajustes posteriores, análises e até novas inclusões no fluxo de erro, evitando a repetição da lógica ao longo do pipeline. ## **Resumo de erros em conectores de loop (For Each, Do While)** O **OnException** de conectores de loop, como o **For Each**, não interrompe a execução do loop. Isso permite compilar ou unificar todas as exceções que ocorrerem durante sua execução, possibilitando o tratamento após o término do loop. Mais informações estão disponíveis na [documentação oficial do **For Each**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/logic/for-each). Uma prática recomendada é armazenar um resumo dos erros na memória do pipeline para exibição posterior, utilizando a cápsula **Add item to session (array)**. Essa cápsula insere os registros em um array chamado `resultList`, que pode ser recuperado posteriormente. É necessário incluir um objeto JSON no payload para adicionar corretamente um item ao array:
Caso a cápsula não esteja disponível, também é possível realizar essa ação diretamente no pipeline utilizando outros conectores, como o [**Session Management**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/structured-data/session-management) e [**JSON Generator**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/json-generator)**:**
{% hint style="info" %} Essa abordagem deve ser usada com cautela, pois o consumo de memória aumenta conforme os registros são adicionados ao array. Em casos de grandes volumes de iteração, recomenda-se utilizar o [**Object Store**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/structured-data/object-store) com o parâmetro **Isolated** ativado, por ser uma alternativa mais adequada. {% endhint %} ## **Revisão de timeouts de conectores de conexão externa em relação ao trigger** Ao configurar um pipeline, é fundamental considerar o tempo limite (**timeout**) dos conectores de conexão externa ([**REST**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/rest-v2), [**DB**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/structured-data/db-v2), [**SOAP**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/soap-v3), [**MongoDB**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/structured-data/mongodb)) em relação ao timeout definido no **trigger**. ### **Importância de alinhar os timeouts** O timeout do trigger deve ser maior do que a soma dos timeouts de todos os conectores externos. Isso garante que o pipeline tenha tempo suficiente para tratar possíveis falhas antes de ser encerrado. ### **Impacto dos tempos de resposta no pipeline** Se os conectores externos tiverem timeouts longos e o trigger tiver um valor inferior, o pipeline poderá ser finalizado antes da conclusão das requisições, gerando inconsistências e dificultando a identificação de erros. Por exemplo, se um pipeline tiver três conectores [**REST**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/rest-v2), cada um com timeout de 30 segundos, o tempo total de execução pode chegar a **90 segundos**. Caso o trigger esteja configurado com um timeout inferior a esse valor, o pipeline será encerrado antes que os conectores finalizem suas execuções. ### **Dicas para configurar os valores de timeout** * **Calcule a soma dos timeouts** dos conectores externos e adicione uma margem de segurança ao timeout do trigger. * **Evite valores excessivamente altos**, pois isso pode comprometer o desempenho da plataforma. * **Considere os processos internos do pipeline**, como transformações e tratamento de erros, ao definir o timeout do trigger. * **Monitore regularmente o tempo de execução** dos conectores e ajuste os timeouts conforme necessário. ## **Validação de erros em pipelines com uso intensivo de Object Store** Quando um pipeline realiza múltiplas operações **CRUD** (Create, Read, Update, Delete) em uma coleção do [**Object Store**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/structured-data/object-store), especialmente de forma simultânea entre diferentes fluxos, é fundamental seguir boas práticas para evitar inconsistências e falhas inesperadas. ### **Prevenção de erros em operações simultâneas** Considere as seguintes práticas: * Ativar a opção **Fail On Error** nos conectores que acessam o **Object Store**, para capturar falhas automaticamente. * Implementar validações após cada operação, usando os conectores [**Assert**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/assert-v2) ou [**Choice**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/logic/choice), para garantir que os dados foram corretamente manipulados. * Monitorar acessos simultâneos ao **Object Store**, evitando sobrecarga e falhas por concorrência. ### **Exemplo de implementação** Se um pipeline realiza leitura no **Object Store** para, em seguida, atualizar os dados, um erro pode ocorrer caso outro processo modifique ou remova esses dados antes da atualização. Para mitigar esse risco, recomenda-se: * **Verificar os dados após a leitura**, garantindo que ainda estão disponíveis. * **Utilizar o conector** [**Assert**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/assert-v2) para validar a presença dos dados esperados. * **Aplicar o conector** [**Choice**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/logic/choice) para definir rotas alternativas caso os dados tenham sido alterados ou removidos. Essas práticas ajudam a minimizar falhas e aumentam a confiabilidade nas interações com o **Object Store**. ## **Comportamento específico do conector Retry** O conector **Retry** possui regras próprias para o tratamento de erros, descritas [nesta documentação](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/logic/retry). É importante compreender o comportamento dos blocos **OnProcess** e **OnException** no contexto do **Retry**. Se o **OnProcess** contém um conector [**Throw Error**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/throw-error) ou está com o parâmetro **Fail On Error** ativado, e se o **OnException** também inclui um **Throw Error**, o Retry encerrará imediatamente suas tentativas, mesmo que ainda haja execuções pendentes. {% hint style="success" %} **Recomendação:** Para garantir que o **Retry** continue suas tentativas até atingir o limite configurado, evite usar o conector **Throw Error** no **OnException**. Assim, o pipeline poderá seguir com as execuções restantes antes de falhar completamente. {% endhint %} ## **"Redundância" de conexão no conector DB V2** Quando a string de conexão do conector [**DB V2**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/structured-data/db-v2) inclui dois ou mais servidores, o timeout definido no campo **Custom Connection Properties** é aplicado individualmente a cada servidor. Por exemplo, com dois servidores e timeout de **30 segundos**: * A primeira tentativa utilizará **30 segundos** para conectar-se ao primeiro servidor. * Caso falhe, o conector tentará o segundo servidor, aplicando novamente **30 segundos**. ### **Gerenciamento das conexões ao banco de dados** O gerenciamento de conexões deve estar alinhado às necessidades do fluxo de integração. Configurações inadequadas podem resultar em: * **Excesso de conexões abertas**, afetando o desempenho do banco e do pipeline. * **Uso desnecessário de recursos**, comprometendo a escalabilidade e a estabilidade. ### **Recomendações para otimização** Revisar e ajustar os parâmetros de conexão pode melhorar o desempenho do pipeline e reduzir o impacto no banco de dados. Os principais parâmetros incluem: * **Pool Size By Actual Consumers** – Define o tamanho do pool com base no número de consumidores reais. * **Exclusive DB Pool** – Indica se o pipeline terá um pool exclusivo. * **Custom Pool** – Permite definir um pool personalizado. * **Keep Connection** – Mantém a conexão ativa entre execuções, o que pode impactar o uso de recursos. Para fluxos com alto volume de operações, revisar essas configurações é essencial para garantir performance e evitar sobrecarga. ## **Conclusão** A gestão adequada de erros na Digibee Integration Platform é essencial para garantir a estabilidade e a eficiência das integrações. Como vimos ao longo do artigo, é importante: * Configurar corretamente os conectores **Fail On Error** e **OnException**. * Entender os comportamentos específicos dos conectores **Retry** e **DB V2**. * Definir timeouts apropriados para conectores externos, alinhando-os com o trigger. * Adotar validações em fluxos concorrentes com **Object Store**, evitando inconsistências. A aplicação dessas boas práticas torna o pipeline mais resiliente, facilitando a detecção e resolução de problemas. Além disso, recomenda-se revisar periodicamente as configurações e estratégias de tratamento de erros, acompanhando a evolução dos processos de integração. Com uma abordagem estruturada, é possível garantir que as soluções desenvolvidas na Digibee sejam robustas, confiáveis e escaláveis.