Pular para conteúdo

MVP 2 — Account Trust, AI Insights e Normalização Financeira (Observabilidade)

Status: canônico · Criado: 2026-05-31 · Issue: #767 Relacionados: MVP-1 Monitoramento e Observabilidade · MVP-2 AI Insights — Auditoria de Precisão · Decisão de stack [J18-1 #487] · Deploy de dashboards [H-P3.4 #499]

Propósito

Este é o documento-pai de observabilidade das três frentes do MVP 2 cujos indicadores de sucesso precisam ser mensuráveis:

  1. Account Trust — confirmação de e-mail e gate de verificação.
  2. AI Insights — geração, custo, qualidade e governança dos insights LLM.
  3. Normalização financeira — erros numéricos e de timezone que corrompem dados.

Ele define a taxonomia única de eventos (web) e métricas (API), mapeia cada índice de sucesso para uma fonte de medição, e fixa a convenção de nomes e as regras anti-PII. Não implementa UI nem instrumentação nova — é o contrato que as tasks Web/API consomem.

Princípio: três eixos, papéis distintos

Observabilidade no Auraxis tem três superfícies, e o erro mais comum é mandar o sinal pra superfície errada. A regra:

Eixo Pergunta que responde Sinais Fonte canônica
Prometheus → Grafana "O sistema está saudável/caro?" (numérico agregado) counters, histograms, gauges API GET /ops/metrics → Alloy → Grafana Cloud
PostHog "O usuário converteu/abandonou?" (comportamental) eventos de produto com props SDK web (posthog-js)
Sentry "O que quebrou e onde?" (erro com stack) exceptions, APM traces SDK api + web

Não misturar: custo de LLM e taxa de 5xx são Prometheus. "Clicou no CTA de upgrade" é PostHog. Stack trace de exceção é Sentry. Um índice de sucesso pode ter sinais em mais de um eixo, mas cada sinal tem uma casa só.

Arquitetura de coleta (decisão #487, deploy #499): Grafana Cloud free tier + Grafana Alloy no EC2 fazendo scrape de /ops/metrics a cada 30s e remote_write. Logs estruturados via Loki na fase seguinte. Detalhe em MVP-1 Monitoramento.

Convenção de nomes (obrigatória)

Artefato Padrão Exemplo
Métrica Prometheus auraxis_<area>_<noun>_<unit/total> auraxis_ai_insight_cost_usd_total
Label de métrica snake_case, cardinalidade baixa e fechada status, period_type, model, reason
Evento de log estruturado event=<domain>.<action> event=auth.email_confirmation_completed
Evento PostHog (web) <domain>_<action> snake_case free_simulation_used, paywall_shown
Alerta <area>: <condição> (<janela>) ai-insights: custo diário > teto (24h)

Labels de alta cardinalidade são proibidos (e-mail, user_id, request_id em métricas Prometheus). Esses vão em logs/PostHog, nunca em label de série.

Eixo 1 — Backend (Prometheus)

Inventário canônico e contrato detalhado vivem em MVP-1 Monitoramento e Observabilidade (seção "AI Insights — métricas, logs e alertas"). Resumo do que está instrumentado e exposto em GET /ops/metrics hoje:

Métrica Tipo Labels Frente Status
auraxis_http_requests_total counter method, endpoint, status_code base ✅ exposto
auraxis_http_request_duration_seconds histogram method, endpoint base ✅ exposto
auraxis_auth_logins_total counter status Account Trust ✅ exposto
auraxis_ai_insight_generated_total counter period_type, dimension AI Insights ✅ exposto
auraxis_ai_insight_tokens histogram period_type AI Insights ✅ exposto
auraxis_ai_insight_snapshot_bytes histogram period_type, truncated AI Insights ✅ exposto
ai_insight_runs_total counter status, period_type AI Insights (#1314) ✅ exposto
ai_insight_cost_usd_total counter model, period_type AI Insights (#1314) ✅ exposto
ai_insight_rejections_total counter reason AI Insights (#1314) ✅ exposto
ai_insight_truncations_total counter field AI Insights (#1314) ✅ exposto
ai_insight_data_quality_total counter flag AI Insights (#1314) ✅ exposto
ai_insight_purges_total counter status AI Insights (#1314) ✅ exposto

Account Trust complementa via logs estruturados (event=auth.email_confirmation_*) — ver Eixo 3. Normalização financeira deve emitir um counter dedicado quando um valor inválido é bloqueado e quando um fallback de timezone é aplicado (gap aberto, ver Checklist).

Métricas a instrumentar (gaps)

Métrica proposta Tipo Labels Frente
auraxis_email_confirmation_total counter action (requested/dispatched/completed/failed), reason Account Trust
auraxis_normalization_rejections_total counter field, reason (invalid_amount/invalid_date) Normalização
auraxis_timezone_fallback_total counter source Normalização

Eixo 2 — Web (PostHog)

Eventos comportamentais. Props nunca carregam PII além do distinct_id que o PostHog já gerencia.

Evento Props Gatilho Índice de sucesso
email_confirmation_prompt_shown surface banner/gate de verificação exibido ativação de conta
email_confirmation_resend_clicked surface usuário pede reenvio fricção de ativação
ai_insight_generated period_type, dimension, cached insight renderizado engajamento insights
ai_insight_monthly_deeplink_opened source abertura do deep link do recap mensal retenção recap
invalid_amount_blocked field, form input numérico inválido barrado no client qualidade de dados
free_simulation_used goal_id free tier usa simulação completa funil freemium (#566)
paywall_shown feature, quota overlay de paywall exibido funil freemium (#566)
upgrade_clicked feature, source CTA de upgrade clicado conversão premium (#566)

Eixo 3 — Logs estruturados (correlação e Account Trust)

Convenção event=<domain>.<action>. Já existentes em email_confirmation_service.py:

  • auth.email_confirmation_requested
  • auth.email_confirmation_instructions_dispatched
  • auth.email_confirmation_completed
  • auth.email_confirmation_failed (com reason=)
  • auth.email_confirmation_url_missing

Correlação por request_id (e trace_id quando existir). No GraphQL, cruzar request_id + graphql_operation + graphql_root_fields.

Mapa: índice de sucesso → fonte → dashboard/consulta

Este é o critério de aceite central do #767 — todo índice tem onde ser medido.

Frente Índice de sucesso Eixo Onde medir
Account Trust taxa de confirmação de e-mail (completed/requested) Prometheus + Logs Grafana: auraxis_email_confirmation_total; Logs Insights por event=auth.email_confirmation_*
Account Trust fricção (reenvios por usuário) PostHog funnel prompt_shown → resend_clicked → completed
AI Insights custo LLM diário/mensal vs teto Prometheus Grafana: rate(ai_insight_cost_usd_total); alerta de teto
AI Insights taxa de rejeição de respostas Prometheus Grafana: ai_insight_rejections_total por reason
AI Insights truncamento de snapshot/resposta Prometheus ai_insight_truncations_total + auraxis_ai_insight_snapshot_bytes{truncated}
AI Insights qualidade de dados (missing_comparison_periods) Prometheus ai_insight_data_quality_total{flag}
AI Insights falha de expurgo (LGPD retention) Prometheus ai_insight_purges_total{status="failed"} → alerta
AI Insights engajamento / abertura do recap PostHog ai_insight_generated, ai_insight_monthly_deeplink_opened
Normalização valores inválidos bloqueados Prometheus + PostHog auraxis_normalization_rejections_total; invalid_amount_blocked
Normalização fallback de timezone aplicado Prometheus auraxis_timezone_fallback_total{source}
Freemium (#566) conversão free→premium PostHog funnel free_simulation_used → paywall_shown → upgrade_clicked

Dashboards e alertas mínimos (escopo do #499)

Dashboards: 5xx por rota · p95/p99 por rota · volume por endpoint · auth failures · custo LLM (manchete) · rejections/truncations/data-quality dos insights · health. Alertas: burst de 5xx (>10/5min) · p95 > 2s · custo LLM diário > teto · taxa de rejeição alta · falha de expurgo · health check down.

Checklist anti-PII (LGPD) — validação obrigatória pelos agentes

Eventos, métricas e logs nunca podem conter:

  • e-mail, nome, telefone ou documento do usuário;
  • prompt bruto enviado ao LLM ou snapshot não sanitizado;
  • observações livres do usuário ou dados bancários reidentificáveis;
  • user_id/request_id/email como label de métrica Prometheus (alta cardinalidade — vão em log/PostHog, não em série).

Como validar: rg pelos nomes de eventos/métricas neste doc; conferir que cada um tem owner e superfície de coleta; revisar props de PostHog e campos de log contra a lista acima antes do merge.

Checklist de instrumentação para as tasks Web/API

  • API: instrumentar gaps (auraxis_email_confirmation_total, auraxis_normalization_rejections_total, auraxis_timezone_fallback_total).
  • Web: emitir os eventos PostHog da tabela do Eixo 2 com as props definidas.
  • Confirmar que toda métrica nova aparece em GET /ops/metrics.
  • #499: subir Alloy + Grafana Cloud e publicar os dashboards/alertas mínimos.
  • Rodar mkdocs build --strict ao alterar este doc.

Referências