Observabilidade e logs do EcomSmart Flow¶

Este documento descreve o contrato de logs implementado no Flow, como acompanhar uma requisição entre os módulos e o que ainda depende da infraestrutura do cluster. Ele complementa o guia de CI/CD e Kubernetes.

Objetivo¶

Os serviços agora escrevem logs estruturados em uma linha JSON no stdout e erros no fluxo normal de logs do contêiner. Isso permite que o coletor do cluster leia todos os pods, interprete campos consistentes e envie os registros para a ferramenta central adotada pela EcomSmart.

flowchart LR
    U[Cliente / WhatsApp] --> CF[Cloudflare]
    CF --> GW[flow-gateway]
    GW --> FE[frontend-entrypoint]
    GW --> WA[whatsapp-entrypoint]
    FE --> B2B[b2b-handler]
    FE --> B2C[b2c-handler]
    FE --> WC[woocommerce-wrapper]
    FE --> AI[genai-wrapper]
    FE --> MK[marketing-campaigns]
    WA --> B2B
    WA --> B2C
    P[Logs stdout/stderr de cada pod] --> C[Coletor do cluster]
    C --> V[Visualizador central: definido pela infraestrutura]

Contrato do log¶

Todo registro JSON possui, no mínimo:

Campo	Exemplo	Finalidade
`timestamp`	`2026-10-01T14:30:00.123Z`	instante UTC
`level`	`INFO`	severidade
`service`	`b2b`	módulo de origem
`environment`	`homologacao`	ambiente de execução
`version`	`0.4.2-hml.3`	release implantada
`logger`	`b2b.access`	logger de origem
`event`	`http_request`	tipo pesquisável do evento
`request_id`	`f5c...`	correlação ponta a ponta
`message`	`http_request`	mensagem resumida

Requisições HTTP também informam method, path, status_code e duration_ms. Exceções incluem tipo, mensagem sanitizada e stack trace.

Os gateways Nginx escrevem o mesmo conjunto principal de campos. Neles a duração é registrada como duration_seconds, que corresponde ao valor nativo do Nginx.

Correlação de uma requisição¶

O gateway aceita um X-Request-ID válido ou gera um identificador. Cada aplicação devolve o valor na resposta e os clientes HTTP internos principais o propagam aos serviços seguintes. Para investigar um onboarding:

obtenha o X-Request-ID da resposta ou encontre o primeiro erro pelo horário;
pesquise o mesmo request_id em todos os serviços;
ordene por timestamp para reconstruir o caminho;
filtre por level=ERROR e confira o primeiro erro, não apenas os efeitos dele.

Exemplo de inspeção direta, enquanto o visualizador central não estiver definido:

kubectl -n flow-hml logs deployment/frontend-entrypoint --since=30m
kubectl -n flow-hml logs deployment/whatsapp-entrypoint --since=30m
kubectl -n flow-hml logs deployment/b2b --since=30m

Para localizar um identificador nos pods do namespace:

kubectl -n flow-hml logs -l app.kubernetes.io/part-of=ecomsmart-flow --since=30m --prefix \
  | grep 'REQUEST_ID_AQUI'

Se o rótulo agregado não retornar todos os workloads, consulte os deployments individualmente com kubectl get deploy -n flow-hml.

Configuração por ambiente e serviço¶

O ConfigMap ecomsmart-observability-config controla:

LOG_FORMAT=json;
ENVIRONMENT=homologacao no overlay de HML.

Cada serviço possui seu próprio ConfigMap com SERVICE_NAME e LOG_LEVEL. Em homologação o padrão é INFO. Para produção, o overlay deve definir a política aprovada pela equipe, normalmente WARNING ou ERROR, sem gerar outra imagem.

A versão vem do ConfigMap ecomsmart-release-info, criado pelo deploy a partir da tag promovida. A mesma imagem pode, portanto, ser configurada de forma diferente em HML e produção.

Privacidade¶

A formatação compartilhada mascara campos cujo nome indica token, senha, autorização, segredo, cookie, chave de API ou telefone. Telefones preservam apenas os quatro últimos dígitos. Payloads descriptografados e argumentos completos de ferramentas não devem ser registrados.

A máscara é uma defesa adicional, não uma autorização para logar credenciais. Novos logs devem preferir eventos e identificadores técnicos, nunca conteúdo de mensagem, senha, token ou payload integral.

Limite desta entrega¶

Esta entrega prepara e padroniza o que as aplicações escrevem. A coleta central, retenção, permissões de leitura, dashboards e alertas pertencem à infraestrutura do cluster. O responsável pelo ambiente ainda deve confirmar:

qual coletor e visualizador estão instalados;
retenção de HML e produção;
acesso do time aos logs;
alertas para erro, indisponibilidade e latência;
filtros ou regras adicionais exigidos pelo coletor.

Checklist de validação em HML¶

fazer build, release e deploy da nova versão;
abrir https://flow-hml.ecomsmart.com.br e executar um fluxo controlado;
confirmar logs JSON de gateway e serviços;
confirmar service=, environment=homologacao e a versão esperada;
confirmar o mesmo request_id em pelo menos dois serviços;
provocar um erro seguro e confirmar stack trace sem segredo ou payload;
validar a ingestão no visualizador central com o dono do cluster.