Arquitetura de métricas

Arquitetura de métricas

A arquitetura das métricas é um sistema de regras, artefatos e serviços que fornecem definições, cálculos reproduzíveis, acesso transparente e uma operação segura dos indicadores em toda a organização. O objetivo é que «MAU», «Retenção D30» ou «ARPU» sejam considerados iguais em todos os dashboards, experiências e relatórios.

1) Princípios

1. Uma única fonte de verdade para fórmulas e guias.
2. Separando a semântica da implementação: a definição de negócio vive numa camada semântica, não em cada SQL/laptop.
3. Versionização de métricas, esquemas e fórmulas (v1→v2) com histórico de migração controlado.
4. Reprodutividade e testabilidade: cálculos determinados, cobertos por testes.
5. Observabilidade: frescura, cumplicidade, consistência e deriva - com SLO e alertas.
6. Segurança e privacidade: PII minimizado, RLS/CLS, auditoria.
7. A operação como código: definições, transformações, políticas - em um repositório com CI/CD.

2) Camadas de arquitetura

Dados de origem: eventos/transações, guias, logs de modelos/infra.
Integração e limpeza: CDC/download incorporativo, deadup, unificação de áreas temporárias.
Modelo de dados (DWH): estrela/floco de neve, medidas de variação lenta (SCD), chaves de aluguel.
Camada semântica de métricas: definições, agregações, filtros, time grain, lógica roll.
Camada calculada: batch/microatch/estrim; janelas, marcas de água, avistamento de chave.
Catálogo e dicionário: «passaporte de métrica», lineage, proprietários, permissões.
Acesso e consumo: BI/dashboard, API métricas, descarga, experimentos/AV.

3) Contratos de dados e métricas

Contrato de origem (eventos/tabelas)

Padrão: campos, tipos, zelo, chave primária.
SLA: frescura (por exemplo, «≤10 minutos de liga»), frequência, paróquia máxima retida.
Qualidade: exclusividade da chave, domínios de valores válidos, timezone, idempotidade.
Mudanças: política de evolução do esquema (backward/forward), plano de deprecação.

Contrato de métrica

Nome/código: 'RET _ D30 _ v2'

Domain/proprietário: Product Analytics

Definição (linguagem humana)

Fórmula: SQL/pseudocode + vitrines de entrada/objetos semânticos

Granularidade/lógica temporal: day/week; point-in-time regras, timezone

Segmentos/filtros padrão

Unidades e divisas (taxa de câmbio/data de conversão)

SLO: frescor ≤ X, precisão ≥ Y, disponibilidade ≥ Z

Versão/histórico de alterações/data de entrada

Guardrails: faixas válidas, regras de vinzorização p1/p99

4) Camada semântica de métricas

• Itens: medidas (data, country, platformom), fatos (events, revenue), métricas (ARPU, Retenção D30), campos computáveis, calendário (escravo/fim de semana, feriados).
• Comportamento do tempo: tabelas de calendário, lajes, cômodos, janelas «deslizantes» (7/30/90).
• Roll e consistência: soma por dia = mês, excluindo dupla contabilidade (distinct users).
• Mix-adjustment: normalização sob um mix constante de canais/países para um YoY honesto.
• Multivaluto/Timzons: adição à moeda básica na data da transação; local e «canônico» do corte UTC.

5) Cálculo: batch, microatch, estirpe

Batch: jobs noturnos/horários, contagem completa/incorporativa, controle de idempotação.
Microatch, janelas de 1 a 15 minutos para dashboards operacionais.
Estrim: eventos através do pneu; janelas (tumbling/sliding/sessions), rótulos de água (late data), exactly-once semântica (Dedup de chave + offset store).

• 'HOP 5m, WINDOW 1h' para KPI operacional;
• 'TUMBLE 1d' para métricas diurnas;
• 'SESSIONS 30m' para sessões.

6) Qualidade e verificabilidade

Os testes de dados são esquemáticos, domínios (intervalo), ligações arbitrárias.
Testes de métricas: invariantes (DAU≤MAU), segmentos impróprios, expectativas de monotonia (cumulativos).
Cruzamentos (reconciação): entre a camada semântica e os relatórios/contabilidade.
Data health: frescura, completeness, duplicados, NULL, saltos anormais.
Métricas à deriva: PSI/KL/JS em fichas-chave, especialmente para métricas ML.

7) Versionização e migração

Versão da fórmula «METRIC_NAME_vN». É proibido alterar a definição sem mudar de versão.

• Side-by-side: v1 e v2 são considerados paralelamente; é feito um teste e treinamento dos usuários.
• Cut-over: alterna os consumidores para v2 na janela de baixa carga; arquivo v1.
• Contagem histórica da história: backfill de acordo com dados históricos; Protocolo de diferença (Relatório Diff).
• Comunicações: changelog, data de entrada, quem for afetado, instruções.

8) Modelo de dados para métricas

Fatos: grão (event _ id, mudanças _ id, user _ day), hora do evento, soma/valor.
Medidas: usuário, dispositivo, geografia, canal, produto, calendário; O tipo SCD é histórico.
Chaves: ID de aluguel, chaves de negócios estáveis, tabelas de conformidade (maping).
Anti-duplicação: regras de identidade (user merge), janelas de «pente» de sessão.

9) Unidades, moedas, sazonalidade

Unidades/formato: unidades explícitas, arredondamentos, escalas (logs/lineares).
Multivaluto: Conversão de curso na data da operação; Guardar a quantia crua e a quantia normalizada.
Sazonalidade: YoY e índices sazonais; efeitos «festivos» individuais.

10) Segurança e acesso

Row-Level Security (RLS): acesso a métricas em um país/marca/parceiro.
Column-Level Security (CLS): camuflando PII/campos financeiros.
Auditoria: quem solicitou a métrica, quais filtros, quais dados exportou.
Diferenciar API: «agregados por papel» vs «descarga detalhada».

11) Observabilidade e SLO

SLO frescura: por exemplo, «KPI operacional - liga ≤ 15 min, diárias até 06:00 locais».
SLO disponibilidade: ≥ 99. 9% para a API/camada semântica.
Alerts: atraso SLO, saltos de métricas, crescimento NULL/duplicados, variação v1 vs v2> X%.
Runbooks: O que fazer em caso de degradação são passos RCA, fallback (por exemplo, mudar para a última «metrica» valida).

12) Experiências e métricas

Guardrail métricas: Latidão, resistência a falhas, FPR/FNR para varreduras.
Definições A/B: conversões, retenção, NSM - através da mesma camada semântica.
Efeito mínimo variável (MDE), power-analise - armazenar parâmetros na ficha de métrica.
Atribuição causal: políticas de mix-adjustment e grupos de controle.

13) API métricas e consumo

Запросы: `GET /metrics/{name}?from=2025-09-01&to=2025-10-01&dims=country,platform&filters=channel:paid`.
Políticos: limites, dinheiro, paginação, «exportações» idumpotentes.
Versões: «X-Metric-Version: v2», avisos de deprecação.

14) Modelos e artefatos

Passaporte de métrica (exemplo)

Código/versão: 'ARPPU _ v3'

Definição: receita média por usuário pagante por período

Формула: `sum(revenue_net) / count_distinct(user_id where paying_flag=1)`

Granularidade: dia; rollup: semana/mês = soma do numerador/soma do denominador

Fontes: 'fact _ payments _ v2', 'dim _ users _ scd'

Unidades: moeda 'base _ ccy'; conversão de curso na data

Filtros padrão: mercados ativos, excluir transações de teste

SLO: frescura ≤ 1h; disponibilidade API ≥ 99. 9%

Guardrails: ARPPU ∈ [0; 10 000]; Vinzorização p1/p99

Proprietários: Monetização Analytics; Data de revisão 2025-10-01

Check-list do lançamento da métrica

• Definição e fórmula estão alinhados, cobertos por testes
• Objeto semântico criado; lineage documentado
• Backfill e acréscimo concluído
• SLO/alertas configurados; runbook pronto
• Direitos e RLS configurados; PII oculto
• As versões antigas foram substituídas em dashboards/experiências
• Changelog/comunicação enviado

pseudo-código SQL point-in-time (exemplo de Retenção D30)

sql
WITH cohort AS (
SELECT user_id, MIN(event_date) AS signup_date
FROM fact_events
WHERE event_type = 'signup'
GROUP BY 1
),
activity AS (
SELECT user_id, event_date
FROM fact_events
WHERE event_type = 'app_open'
),
ret AS (
SELECT c. signup_date,
COUNT(DISTINCT CASE WHEN a. event_date = c. signup_date + INTERVAL '30 day' THEN a. user_id END) AS returned,
COUNT(DISTINCT c. user_id) AS cohort_size
FROM cohort c
LEFT JOIN activity a
ON a. user_id = c. user_id
AND a. event_date BETWEEN c. signup_date AND c. signup_date + INTERVAL '30 day'
GROUP BY 1
)
SELECT signup_date, returned / cohort_size AS retention_d30
FROM ret;

15) Erros frequentes e como evitá-los

As edições silenciosas das fórmulas são sempre através da versão e changelog.
As métricas são diferentes em cada laptop: obrigue a uma camada semântica/API.
Times/moedas incoerentes: calendário centralizado e tabela FX.
Dupla contabilidade de usuários: regras de roll e chaves exclusivas.
Frescura opaca: mostre claramente a liga/hora de atualização.
Dependência de um engenheiro, tudo como um código, com um revo e um oncoll.

Resultado

A arquitetura de métricas é um dicionário + camada semântica + cálculo confiável + overnance e SLO. Seguindo os princípios descritos (contratos, testes, versões, observabilidade, segurança), você transforma as métricas de «discussões sobre números» em um mecanismo sustentável de gerenciamento de produtos e negócios.