SYS/001 Observa

Laboratório local de pedidos distribuídos para demonstrar diagnóstico, compensação e recuperação com observabilidade de ponta a ponta.

01 / Contexto e problema

Observa é um laboratório local para diagnosticar e recuperar uma jornada de pedidos distribuída. Quatro serviços trocam eventos de domínio; pedidos, pagamentos e estoque são sintéticos. O objetivo é tornar visível o caminho entre um estado de negócio, a trace correspondente e os logs da mesma execução.

Três resultados demonstráveis: CONFIRMED, FAILED e CANCELLED; o caso CANCELLED inclui compensação do pagamento.
A demonstração usa Kubernetes local, sem cobrança, notificação externa ou cloud obrigatória.
OrderFlow foi referência funcional somente leitura; Observa é um projeto separado.

02 / Papel e escopo

O repositório apresenta serviços, contratos, infraestrutura, scripts de verificação e runbooks como trabalho de engenharia do projeto. A evidência pública permite avaliar comportamento e decisões sem atribuir resultados a uma operação comercial externa.

Fluxo e contratos de eventos para Order, Payment, Inventory e Notification.
Outbox, deduplicação e recuperação testados com PostgreSQL descartável e no cluster local.
Instrumentação para correlacionar métricas, traces e logs no Grafana.

03 / Arquitetura do sistema

Order e Notification usam Python; Payment e Inventory usam Node.js. Kafka transporta eventos, PostgreSQL persiste efeitos, e a telemetria chega a uma stack observável no Kubernetes local. O processamento é pelo menos uma vez; a deduplicação por event_id evita efeitos duplicados.

Pagamento aprovado e estoque reservado levam a CONFIRMED; pagamento recusado leva a FAILED.
Estoque indisponível após aprovação solicita e confirma estorno antes de CANCELLED.
A ordem observada no fluxo normal vale por tópico e partição; replay e estacionamento não preservam a posição original.

04 / Modelo de dados

O estado do pedido e os efeitos dos consumidores são persistidos em PostgreSQL. Payment grava decisão, marcador de processamento e outbox na mesma transação. event_id permite reconhecer redelivery sem repetir o efeito.

O harness força falha entre commit e offset para verificar redelivery com um efeito por event_id.
Na recuperação de Inventory, a verificação exige uma reserva e um evento terminal.
IDs, credenciais e evidências brutas ficam em .local/, fora do Git; os dados são sintéticos.

05 / Decisões de engenharia

O laboratório privilegia falhas observáveis e ensaios reproduzíveis. Outbox e deduplicação atendem à entrega pelo menos uma vez; o painel não substitui a prova dos efeitos persistidos.

Relays com claim transacional em PostgreSQL foram testados com dois claimers. ACK antes de commit ainda pode republicar; deduplicação continua necessária.
KEDA e HPAs são optativos. Um ensaio controlado atribuiu a escala de Payment ao lag Kafka, sem alegar alta disponibilidade.
Alertas são experimentais; um ensaio observou o alerta de Payment disparar e desaparecer após restauração.

06 / Implementação

O README oferece um percurso executável em PowerShell: instalar ferramentas, subir o perfil minikube dedicado, conferir status e contratos, executar os três cenários e testar recuperação. O runbook mostra como abrir Grafana por port-forward.

Comandos centrais: ./scripts/mvp.ps1 up, status, contract, demo e recovery, nesta ordem.
check.ps1 cobre builds, lint, tipos, testes, imagens, auditorias, segredos, manifests e regras Prometheus; a CI pública passou no commit 5d3267e.
O perfil observa-spike0 é local e dedicado; o README documenta pré-requisitos e sua remoção.

07 / Experiência de produto

O avaliador começa pelos estados finais da demo e continua no dashboard observa-mvp. Um exemplar recente abre a trace no Tempo; Related logs mostra registros no Loki; View trace retorna à mesma execução.

O dashboard apresenta eventos, erros, duração e efeitos de negócio, além de exemplars.
O runbook permite reproduzir status e demo sem passos manuais adicionais no fluxo de domínio.
A navegação Grafana exige inspeção visual; a síntese textual não certifica os cliques da interface.

08 / Resultados

A síntese pública do MVP registra os três estados concluídos. A recuperação registrou pedido CONFIRMED após recriação de Inventory com uma reserva. A validação pós-MVP acrescenta ensaios de relays, escala, alerta e falhas locais.

Um baseline local posterior concluiu 30/30 pedidos sequenciais; os p95 observados por cenário foram 2,309 s, 1,129 s e 2,228 s.
No checkout limpo, a inspeção percorreu exemplar, trace de quatro serviços com 21 spans, 10 logs do mesmo trace_id e retorno à trace.
São observações locais com dados sintéticos, não percentis de produção nem SLO aprovado.

09 / Retrospectiva

O projeto demonstra diagnóstico e recuperação em condições controladas. Um nó, um broker e dados sintéticos delimitam a conclusão: recriar pods demonstra recuperação eventual, não continuidade durante uma falha nem alta disponibilidade.

Replay, estacionamento e concorrência têm limites de ordenação documentados.
A hipótese experimental de 95% dos pedidos em até 5 s não foi adotada como SLO.
Qualquer afirmação sobre produção exigiria ambiente e carga representativos.