Como enviar logs de pipeline para sistemas externos de monitoramento

Saiba como exportar logs de pipelines para sistemas de monitoramento fora da Digibee Integration Platform.

Os logs ajudam a entender o que aconteceu durante a execução dos pipelines e a investigar comportamentos inesperados. Você pode visualizá-los diretamente na página de Pipeline Logs em Monitor.

No entanto, se você precisar monitorar logs usando sistemas externos como ElasticSearch, Kibana, Graylog ou Splunk, é possível criar fluxos dedicados usando o padrão Log Stream.

Arquitetura: Padrão Log Stream

O padrão Log Stream utiliza o Event Broker interno da Digibee para desacoplar o envio de logs do fluxo principal, evitando sobrecarga ou atrasos na execução primária da integração. Esse padrão envolve a divisão do fluxo em dois pipelines:

1. Pipeline de Regra de Negócio: Organiza a lógica de negócio principal e gera os eventos de log.

2. Pipeline de Log Stream: Escuta os eventos e exporta os logs para os serviços externos desejados.

Veja abaixo como configurar cada um desses pipelines.

Antes de implementar essa abordagem, saiba mais sobre arquitetura orientada a eventos.

Diagrama: Padrão Log Stream

1

Crie o pipeline de Regra de Negócio

Esse pipeline define a lógica principal do fluxo e gera os eventos de log.

No local onde normalmente você usaria um conector Log, siga os passos abaixo para melhorar o gerenciamento dos logs com o padrão Log Stream:

1. (Opcional) Armazene o contexto com Session Management

Use o conector Session Management (no modo “put data”) para armazenar valores-chave do contexto do pipeline, como informações do usuário ou detalhes do erro, que serão recuperados antes de publicar os logs. Isso garante que todos os dados relevantes estejam disponíveis ao acionar o pipeline de Log Stream.

1. Use o Block Execution

O conector Block Execution cria dois subfluxos:

• OnProcess (obrigatório): Caminho principal de execução.

• OnException: Acionado apenas se ocorrer um erro no subfluxo OnProcess.

Dentro de OnProcess, adicione:

• Um conector Log

• Um conector Session Management (no modo “get data”) para recuperar o contexto armazenado

• Um Event Publisher para acionar o pipeline de Log Stream

Configure o Event Publisher para enviar o payload de log desejado, por exemplo:

{
  "timestamp": "2025-05-05T12:00:00Z",
  "pipelineId": "customer-onboarding",
  "executionId": "abc123",
  "message": "Customer onboarding started"
}

Dica: Use variáveis como {{ metadata.$ }} para extrair dados do fluxo e do pipeline e facilitar a análise durante um processo de investigação. Saiba mais sobre como referenciar metadados usando Double Braces.

Dentro de OnException, adicione um conector Throw Error para evitar falhas silenciosas.

Embora o padrão Log Stream seja especialmente útil para capturar e gerenciar logs de erro, o que é uma prática comum em ambientes de produção, ele também oferece suporte a diversos outros casos de uso, como:

• Eventos de execução bem-sucedida

• Logs de auditoria

• Eventos de negócio personalizados

A estrutura resultante do pipeline de Regra de Negócio (onde normalmente seria usado um conector Log) deve se parecer com esta:

Exemplo de pipeline de Regra de Negócio

2

Configure o pipeline de Log Stream

Esse pipeline recebe e processa os eventos de log. Siga estas etapas para configurá-lo:

1. Configure o trigger

Defina o Event Trigger como trigger (gatilho) do pipeline e configure-o para corresponder ao nome do evento usado no Event Publisher do pipeline de Regra de Negócio. Isso garante que o pipeline de Log Stream seja acionado sempre que um evento de log for publicado.

1. Encaminhe os logs para ferramentas externas

Use conectores como REST V2 ou SOAP V3 para enviar os dados de log às ferramentas externas. Você pode:

• Enviar logs para vários destinos

• Encaminhar logs condicionalmente usando o conector Choice

No exemplo abaixo, um conector Choice direciona os logs para Graylog ou Kibana via conector REST V2:

Evite colocar conectores Log em excesso no seu pipeline. Isso pode prejudicar o desempenho e aumentar o tamanho necessário para o deploy.

Informações adicionais

Boas práticas para chamadas externas de log

• Envolva chamadas externas em um conector Block Execution.

  • OnProcess: Use o conector REST e valide as respostas com um conector Choice seguido de um Throw Error, ou use um conector Assert.

  • OnException: Envie alertas para falhas de entrega com o conector Email V2, seguido de um Throw Error.

• Ative a lógica de tentativas (retry) nas configurações avançadas do conector REST V2.

• Oculte ou mascare informações sensíveis (como PII, credenciais, tokens).

• Use controles por campo ou Cápsulas para garantir conformidade com políticas de proteção de dados.

Saiba mais sobre Práticas essenciais para proteger informações sensíveis em pipelines com a Digibee.

Alternativa: Use Cápsulas

Em vez de criar um pipeline dedicado para Log Stream, considere usar Cápsulas para centralizar e reutilizar a lógica de manipulação de logs.

Saiba mais sobre o uso de Cápsulas.

Desafio prático

Coloque seu conhecimento em prática! Experimente o desafio sobre o padrão Log Stream no Digibee Academy.