# Como enviar logs de pipeline para sistemas externos de monitoramento

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**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/dashboards/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.

{% hint style="info" %}
Antes de implementar essa abordagem, saiba mais sobre [arquitetura orientada a eventos](https://app.gitbook.com/s/XfrDexGOLMin51pAiWkq/best-practices/event-oriented-architecture).
{% endhint %}

<figure><img src="https://content.gitbook.com/content/3ANg0NQQeslB7Og5K7Ah/blobs/PWDtpFPIsdCv0A4VrlOu/Untitled%20design%20(2).png" alt=""><figcaption><p>Diagrama: Padrão Log Stream</p></figcaption></figure>

{% stepper %}
{% step %}

### 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**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/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**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/structured-data/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**.

2. #### **Use o Block Execution**

O [conector **Block Execution**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/logic/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**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/log)
* Um [conector **Session Management**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/structured-data/session-management) (no modo “get data”) para recuperar o contexto armazenado
* Um [**Event Publisher**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/queues-and-messaging/event-publisher) para acionar o pipeline de **Log Stream**

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

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

{% hint style="success" %}
**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](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/double-braces/how-to-reference-data-using-double-braces#ddcmojcg6oul).
{% endhint %}

Dentro de **OnException**, adicione um [conector **Throw Error**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/throw-error) para evitar falhas silenciosas.

{% hint style="info" %}
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
  {% endhint %}

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

<figure><img src="https://content.gitbook.com/content/3ANg0NQQeslB7Og5K7Ah/blobs/oYEKB2SHRLFchiVErQP3/Portuguese.png" alt=""><figcaption><p>Exemplo de pipeline de Regra de Negócio</p></figcaption></figure>
{% endstep %}

{% step %}

### 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**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/triggers/messaging-and-events/event) 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.

2. #### **Encaminhe os logs para ferramentas externas**

Use conectores como [**REST V2**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/rest-v2) ou [**SOAP V3**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/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**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/logic/choice)

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

<figure><img src="https://content.gitbook.com/content/3ANg0NQQeslB7Og5K7Ah/blobs/LPMemBTyB3HIo9GVBFq1/image.png" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Evite colocar conectores **Log** em excesso no seu pipeline. Isso pode prejudicar o desempenho e aumentar o tamanho necessário para o deploy.
{% endhint %}
{% endstep %}
{% endstepper %}

## **Informações adicionais**

### **Boas práticas para chamadas externas de log**

* Envolva chamadas externas em um [conector **Block Execution**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/logic/block-execution).
  * **OnProcess:** Use o conector [**REST**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/rest-v2) e valide as respostas com um conector [**Choice**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/logic/choice) seguido de um [**Throw Error**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/throw-error), ou use um conector [**Assert**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/assert-v2).
  * **OnException**: Envie alertas para falhas de entrega com o conector [**Email V2**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/email-v2), seguido de um [**Throw Error**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/throw-error).
* Ative a lógica de tentativas (retry) nas configurações avançadas do conector [**REST V2**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/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](https://app.gitbook.com/s/XfrDexGOLMin51pAiWkq/use-cases/key-practices-for-securing-sensitive-information).

### **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](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/build-overview/capsulas).

### **Desafio prático**

Coloque seu conhecimento em prática! Experimente o [desafio sobre o padrão Log Stream no Digibee Academy](https://digibee.academy/challenge-log-stream-pt/?lang=pt-br).