Arquitectura métrica

Arquitectura de métricas

La arquitectura métrica es un sistema de reglas, artefactos y servicios que proporcionan definiciones inequívocas, cálculo reproducible, acceso transparente y operación confiable de los indicadores en toda la organización. El objetivo es que "MAU", "Retention D30" o'ARPPU "se consideren iguales en todos los dashboards, experimentos e informes.

1) Principios

1. Una única fuente de verdad para fórmulas y guías.
2. Separar la semántica de la implementación: la definición de negocio vive en la capa semántica, no en cada SQL/portátil.
3. Versionar métricas, esquemas y fórmulas (v1→v2) con migración gestionada del historial.
4. Reproducibilidad y probabilidad: los cálculos son deterministas, cubiertos por pruebas.
5. Observabilidad: frescura, plenitud, consistencia y deriva - con SLO y alertas.
6. Seguridad y privacidad: minimización de PII, RLS/CLS, auditoría.
7. Operación como código: definiciones, transformaciones, políticas - en un repositorio con CI/CD.

2) Capas de arquitectura

Datos de origen: eventos/transacciones, guías, registros de modelos/infra.
Integración y limpieza: CDC/carga incremental, dedoup, unificación de zonas temporales.
Modelo de datos (DWH): estrella/copo de nieve, mediciones de cambio lento (SCD), llaves sustitutas.
Capa semántica de métricas: definiciones únicas, agregaciones, filtros, tiempo de grano, lógica de rollo.
Capa calculada: batch/microbatch/stream; ventanas, marcas de agua, dedoup en llaves.
Catálogo y diccionario: «pasaporte métrico», lineage, propietarios, derechos.
Acceso y consumo: BI/dashboards, métricas API, descargas, experimentos/AV.

3) Contratos de datos y métricas

Contrato de origen (eventos/tablas)

Esquema: campos, tipos, nulidad, clave principal.
SLA: frescura (por ejemplo, «≤10 minutes lag»), frecuencia, máxima parroquia detenida.
Calidad: singularidad de la clave, dominios de valores válidos, timezone, idempotencia.
Cambios: política de evolución del esquema (backward/forward), deprecation-plan.

el Contrato de la partida de nacimiento

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

Domaine/propietario: Product Analytics

Definición (en lenguaje humano)

Fórmula: SQL/pseudocódigo + escaparates de entrada/objetos semánticos

Granularidad/lógica temporal: día/semana; reglas de punto en tiempo, timezone

Segmentos/filtros predeterminados

Unidades y monedas (tipo de cambio/fecha de conversión)

SLO: frescura ≤ X, precisión ≥ Y, disponibilidad ≥ Z

Versión/historial de cambios/fecha de entrada

Guardrails: rangos válidos, reglas de vinsorización p1/p99

4) Métricas de capa semántica

• Elementos: medidas (fecha, país, plataforma), hechos (eventos, revenue), métricas (ARPU, Retention D30), campos computables, calendario (esclavo/fin de semana, vacaciones).
• Comportamiento del tiempo: tablas de calendario, lagunas, cohortes, ventanas «deslizantes» (7/30/90).
• Rollo y consistencia: suma por día = mes, mientras que excluye la doble contabilidad (distinct users).
• Mix-adjustment: normalizar bajo una mezcla permanente de canales/países para un YoY honesto.
• Multivalor/temporizadores: llevar a la moneda base en la fecha de la transacción; los cortes UTC locales y «canónicos».

5) Cálculo: batch, microbatch, stream

Batch: jobs nocturnos/por hora, recuentos completos/incrementales, control de idempotencia.
Microbatch: ventanas 1-15 minutos para dashboards operativos.
Stream: eventos a través del bus; ventanas (tumbling/sliding/session), marcas de agua (data late), semántica exactly-once (dedoup por clave + offset store).

• 'HOP 5m, WINDOW 1h' para KPI operativos;
• 'TUMBLE 1d' para métricas diurnas;
• 'SESIÓN 30m' para sesiones.

6) Calidad y verificabilidad

Pruebas de datos: esquemáticas, dominios (rangos), enlaces de referencia.
Pruebas métricas: invariantes (DAU≤MAU), segmentos no vacíos, expectativas de monotonía (acumulativos).
Conciliaciones (reconciliation): entre la capa semántica y los informes de referencia/contabilidad.
Salud de datos: frescura, completeness, duplicados, proporción NULL, saltos anormales.
Métricas de deriva: PSI/KL/JS en fichas clave, especialmente para métricas ML.

7) Versificación y migración

Versión de fórmula: 'METRIC _ NAME _ vN'. Está prohibido cambiar «silenciosamente» la definición sin cambiar la versión.

• Side-by-side: v1 y v2 se consideran en paralelo; se lleva a cabo la conciliación y la capacitación de los usuarios.
• Cut-over: cambiar los consumidores a v2 en la ventana de baja carga; archivo v1.
• Recuento de la historia: backfill según datos históricos; protocolo de diferencia (informe diff).
• Comunicaciones: changelog, fecha de entrada, a quién afectará, instrucciones.

8) Modelo de datos para métricas

Hechos: grano (event_id, transaction_id, user_day), tiempo del evento, suma/magnitud.
Medidas: usuario, dispositivo, geografía, canal, producto, calendario; Tipo SCD para la historicidad.
Claves: ID subrogado, claves de negocio estables, tablas de coincidencia (mapping).
Anti-toma: reglas de identidad (user merge), ventanas de «pegamento» de las sesiones.

9) Unidades, monedas, estacionalidad

Unidades/formato: unidades explícitas, redondeos, escalas (logs/lineales).
Multivalor: conversión por tipo de cambio en la fecha de la operación; almacenar tanto «crudo» como una cantidad normalizada.
Estacionalidad: YoY e índices estacionales; efectos individuales «festivos».

10) Seguridad y acceso

Row-Level Security (RLS): acceso a métricas en la sección País/Marca/Socio.
Seguridad de nivel de columna (CLS): enmascarar campos PII/financieros.
Auditoría: quién solicitó la métrica, qué filtros, qué datos exportó.
Diferenciación de API: «agregados por roles» vs «descargas detalladas».

11) Observabilidad y SLO

SLO de frescura: por ejemplo, «los KPI operativos son ≤ 15 min, los diarios son hasta las 06:00 hora local».
SLO disponibilidad: ≥ 99. 9% para la capa API/semántica.
Alertas: retraso de SLO, saltos de métricas, crecimiento de NULL/duplicados, discrepancia v1 vs v2> X%.
Runbooks: qué hacer cuando se degradan son los pasos de RCA, fallback (por ejemplo, cambiar a la última «métrica de snepshot» válida).

12) Experimentos y métricas

Métricas de Guardrail: latencia, tolerancia a fallas, FPR/FNR para puntuaciones.
Definiciones uniformes para A/B: conversiones, retención, NSM - a través de la misma capa semántica.
Efecto mínimo distinguible (MDE), análisis de potencia: almacenar parámetros en una tarjeta métrica.
Atribución causal: políticas por mix-adjustment y grupos de control.

13) API métricas y consumo

Запросы: `GET /metrics/{name}?from=2025-09-01&to=2025-10-01&dims=country,platform&filters=channel:paid`.
Políticas: límites, caché, paginación, «exportaciones» idempotentes.
Versiones: encabezado 'X-Metric-Version: v2', advertencias de depreción.

14) Patrones y artefactos

Pasaporte métrico (ejemplo)

Código/versión: 'ARPPU _ v3'

Definición: ingresos medios por usuario pagador durante el período

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

Granularidad: día; rollup: semana/mes = suma del numerador/suma del denominador

Fuentes: 'nat _ payments _ v2', 'dim _ users _ scd'

Unidades: moneda 'base _ ccy'; conversión por tipo de cambio en la fecha

Filtros predeterminados: mercados activos, excluir transacciones de prueba

SLO: frescura ≤ 1 h; Disponibilidad de la API ≥ 99. 9%

Guardrails: ARPPU ∈ [0; 10 000]; vinzorización p1/p99

Propietarios: Monetization Analytics; Fecha de la auditoría: 2025-10-01

Check-list

• Definición y fórmula acordadas, cubiertas por pruebas
• Se ha creado un objeto semántico; lineage documentado
• Backfill y las conciliaciones con el referente completado
• SLO/alertas personalizadas; runbook listo
• Derechos y RLS configurados; PII oculta
• En los dashboards/experimentos se han sustituido las versiones antiguas
• Changelog/comunicación enviada

Seudocode SQL punto en tiempo (ejemplo Retention 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) Errores frecuentes y cómo evitarlos

Ediciones silenciosas de fórmulas: siempre a través de la versión y changelog.
Métricas «en cada laptop de manera diferente»: forzar la capa semántica/API.
Temporizaciones/monedas inconsistentes: calendario centralizado y tabla FX.
Doble contabilidad de usuarios: reglas de rollup y claves únicas.
Frescura opaca: muestra explícitamente el valor/tiempo de actualización.
Dependencia de un ingeniero: todo es como código, con rugido y oncol.

Resultado

La arquitectura métrica es un diccionario + capa semántica + cálculo confiable + gobierno y SLO. Siguiendo los principios descritos (contratos, pruebas, versiones, observabilidad, seguridad), se convierten las métricas de «disputas sobre números» a un mecanismo sostenible de gestión de productos y negocios.