3.4 KiB

Raw Blame History

🕵️ 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):

{"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

DEBUG: Payloads brutos, estados de variáveis. Habilite apenas durante dev/diagnóstico.
INFO: Eventos de Negócio. "Usuário Criado", "Job Iniciado", "Pagamento Processado".
WARN: Problemas recuperáveis. "Tentativa 1/3 falhou", "Config ausente (usando padrão)".
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?

3.4 KiB Raw Blame History