# 🕵️ Padrões de Observabilidade & Logging (O Gravador "Caixa Preta")

**Público:** Desenvolvedores & Agentes SRE (Arthur Mendes).
**Objetivo:** Transformar "Quebrou" em "Quebrou na linha 42 por causa da variável X".

> [!CRITICAL]
> **O Mandato Arthur:**
> "Logs são primeiro para máquinas, segundo para humanos. Se eu não posso usar `grep` ou `jq` no seu log, ele é ruído inútil."

## 1. 📝 Protocolo de Logging (Estruturado & Padronizado)

### O Formato: Linhas JSON
Logs de texto estão mortos. Vida longa ao JSON.
**Por que?** Porque Zabbix, ELK e scripts Python simples podem parseá-lo instantaneamente.

**❌ RUIM (Texto Não Estruturado):**
`[2024-01-01 10:00] ERROR: User failed login. ID: 123`

**✅ BOM (JSON Estruturado):**
```json
{"timestamp": "2024-01-01T10:00:00Z", "level": "ERROR", "event": "auth_failure", "user_id": 123, "reason": "invalid_password", "correlation_id": "abc-123"}
```

### Os 4 Níveis de Severidade
1.  **DEBUG**: Payloads brutos, estados de variáveis. *Habilite apenas durante dev/diagnóstico.*
2.  **INFO**: Eventos de Negócio. "Usuário Criado", "Job Iniciado", "Pagamento Processado".
3.  **WARN**: Problemas recuperáveis. "Tentativa 1/3 falhou", "Config ausente (usando padrão)".
4.  **ERROR**: Intervenção do operador necessária. Stack traces, perda de conexão com DB.

### A Saída "12-Factor"
*   **Containers:** Sempre escreva para `stdout` / `stderr`. Nunca escreva em arquivos locais dentro de um container (a menos que use um volume compartilhado para trilhas de auditoria específicas).
*   **Rastreabilidade:** Toda requisição/job DEVE gerar um `correlation_id` (UUID) na borda e passá-lo por toda a stack.

## 2. 👁️ Monitoramento & Integração Zabbix

Nosso ecossistema de monitoramento é centrado no **Zabbix**. Sua aplicação deve ser "Zabbix-Friendly".

### A. O Endpoint de Saúde (`/health`)
Todo serviço HTTP DEVE permitir que um Cenário Web do Zabbix o verifique.
*   **Caminho:** `/health`
*   **Resposta:** `200 OK` (Corpo JSON opcional mas recomendado: `{"status": "up", "db": "up"}`).
*   **Timeout:** Deve responder em < 200ms.

### B. O Padrão "Zabbix Trapper" (Push Metrics)
Para jobs em lote ou workers assíncronos (Agentes CrewAI), não espere ser raspado. **EMPURRE** a métrica usando `zabbix_sender`.

*   **Python:** Use `py-zabbix` ou socket puro.
*   **Padrão de Chave:** `app.module.metric` (ex: `crew.infra.task_duration`).
*   **Quando usar:** Quando uma tarefa específica termina (ex: "Agente compilou relatório em 45s").

### C. Palavras-Chave de Monitoramento de Log
Se você deve depender de Raspadores de Log (Zabbix Agent Active), use estas "Palavras-Chave de Gatilho" para acordar o Arthur:
*   `[SECURITY_BREACH]`: Alerta de alta prioridade imediato.
*   `[DATA_LOSS]`: Alerta crítico.
*   `[DEPRECATED]`: Alerta de aviso.

## 3. 🚨 Filosofia de Alerta (Inteligência Acionável)

Não logue um erro se você já lidou com ele graciosamente.
*   **Erro Tratado:** Log com `WARN`. (Sem pager).
*   **Código Não Tratado:** Log com `ERROR`. (Acorde o Arthur).

## 4. 🤖 O "Autodiagnóstico" do Agente (Auditoria de Log)

Antes de considerar uma tarefa completa, rode esta auditoria:

- [ ] **Checagem JSON:** Minha saída é parseável?
- [ ] **Contexto:** Incluí `user_id`, `file_name` ou `job_id`?
- [ ] **Silêncio:** Removi todos os `print(var)` usados para debug?
- [ ] **Correlação:** Posso rastrear este erro de volta à requisição do usuário?