Telemetría y recopilación de eventos

1) Nombramiento y principios

• Flujo de eventos único y predecible para análisis, antifraude, RG, cumplimiento y ML.
• Rastreo de extremo a extremo (user/session/request/trace) y reproducibilidad.
• Minimizar el PII y cumplir con los requisitos de privacidad.

Принципы: schema-first, privacy-by-design, idempotency-by-default, observability-by-default, cost-aware.

2) Taxonomía de eventos

Pago: 'pago. deposit`, `payment. withdrawal`, `payment. chargeback`.
Juegos: 'game. session_start/stop`, `game. bet`, `game. payout`, `bonus. applied`.
Personalizado: 'auth. login`, `profile. update`, `kyc. status_changed`, `rg. limit_set`.
Quirófanos: 'api. request`, `error. exception`, `release. deploy`, `feature. flag_changed`.
Cumplimiento: 'aml. alert_opened`, `sanctions. screened`, `dsar. requested`.

Cada tipo tiene un propietario (domain owner), un esquema y un SLO de frescura.

3) Esquemas y contratos

• `event_time` (UTC), `event_type`, `schema_version`, `event_id` (UUID/ULID),
• `trace_id`/`span_id`, `request_id`, `user. pseudo_id`, `session_id`,

json
{
"event_id": "01HFY1S93R8X",
"event_time": "2025-11-01T18:45:12. 387Z",
"event_type": "game. bet",
"schema_version": "1. 4. 0",
"user": {"pseudo_id": "p-7a2e", "age_band": "25-34", "country": "EE"},
"session": {"id": "s-2233", "device_id": "d-9af0"},
"game": {"id": "G-BookOfX", "provider": "StudioA", "stake": {"value": 2. 00, "currency": "EUR"}},
"ctx": {"ip": "198. 51. 100. 10", "trace_id": "f4c2...", "request_id": "req-7f91"},
"labels": {"market": "EE", "affiliate": "A-77"}
}

Evolución de los esquemas: versiones semánticas; backward-compatible: agregue campos nullables; breaking - sólo en la nueva versión ('/v2 ') con un periodo de grabación doble.

4) Instrumentación: dónde y cómo

4. 1 Cliente (Web/Mobile/Desktop)

Telemetría SDK con buffer local, envío de batch, retrés exponenciales.
Eventos automáticos: visitas, clics, visibilidad de bloques, web-vitals (TTFB, LCP, CLS), errores JS.
Identificadores: 'device _ id' (sostenible pero privado), 'session _ id' (actualizado), 'user. pseudo_id`.
Protección contra «ruidos»: dedoop por 'event _ id', trottling, sampling de cliente-lado.

4. 2 Servidor/backend

Las envolturas de Logger/Traiser (OpenTelemetry) → emites de eventos de dominio.
Desplazamiento obligatorio de 'trace _ id' desde edge/gateway a todos los servicios de descarga.
Patrón de outbox para la publicación transaccional de eventos de dominio.

4. 3 Proveedores/terceros

Conectores (PSP/KYC/studio) con normalización a circuitos host; adaptadores de versión.
Firma/comprobación de integridad de payload, registro perimetral (ingest audit).

5) OpenTelemetry (OTel)

Tracks: cada consulta recibe un 'trace _ id'; asociamos logs/eventos a través de 'trace _ id '/' span _ id'.
Logs: usamos OTel Logs/transductores; etiquetas de entorno 'service. name`, `deployment. env`.
Métricas: RPS/latency/error-rate por servicios, métricas de negocio (GGR, conversión).
Collector: punto único de recepción/búfer/exportación a Kafka/HTTP/grafic. pila.

6) Identificadores y correlación

'event _ id' - singularidad e idempotencia.
`user. pseudo_id' es una pseudonimización estable (mapping por separado y limitada).
'session _ id', 'request _ id', 'trace _ id', 'device _ id' son obligatorias para el análisis de extremo a extremo.
Consistencia de ID a nivel de puerta de enlace API y SDK.

7) Muestreo y control de volumen

Reglas: por-evento-tipo, por-mercado, dinámico (adaptativo) por carga.
Eventos filmados con precisión: pagos/cumplimiento/incidentes - no se muestrean.
Eventos analíticos: se permite un 10-50% con pesos correctivos en las vitrinas.
Downsampling server-side: permítase para métricas de alta frecuencia.

8) Privacidad y cumplimiento

Minimizar PII: tokenizar PAN/IBAN/email; IP → GEO/ASN en ingest.
Regionalización: envíe a ingest-endpoints regionales (EEA/UK/BR).
DSAR/RTBF: soporte para ocultación selectiva de proyecciones; registro de transacciones legales.
Políticas de retención: tiempo por tipo (análisis más corto, regulatorio más largo); Legal Hold.

9) Transporte y amortiguación

Cliente → Edge: HTTPS (HTTP/2/3), 'POST/telemetry/batch' (hasta 100 eventos).
Edge → Shina: Kafka/Redpanda con partido por 'user. pseudo_id`/`tenant_id`.
Formatos: JSON (ingest), Avro/Protobuf (en bus), Parquet (en lago).
Fiabilidad: retraídas con jitter, DLQ, aislamiento poison-pill.

json
{
"sdk": {"name":"igsdk-js","version":"2. 7. 1"},
"sent_at": "2025-11-01T18:45:12. 500Z",
"events": [ {... }, {... } ]
}

10) Fiabilidad e idempotencia

Client-generated 'event _ id' + servidor dedup por '(event_id, source)'.
Outbox en servicios, Exactly-Once-semántica en subprocesos (keyed state + dedupe).
Orden dentro de la clave: partición por 'usuario/sesión'.
Control de tiempo: NTP/PTP, deriva válida (por ejemplo, ≤ 200 ms), 'received _ at' en el servidor.

11) Calidad de telemetría (TQ) y SLO

Completeness: ≥ 99. 5% de los eventos de tipos críticos por T.
Freshness: p95 entrega retrasada a Silver ≤ 15 min.
Correctness: circuitos válidos ≥ 99. 9%, drop-rate < 0. 1%.
Trace coverage: porcentaje de consultas con 'trace _ id' ≥ 98%.
Costo/GB: presupuesto objetivo para ingest/almacenamiento por dominio.

12) Observabilidad y dashboards

• Lag ingest (p50/p95) por fuente y región.
• Completeness por tipo de evento y mercado.
• Errores de validación de esquemas/oversized-payloads.
• Mapa de versiones de SDK y porcentaje de clientes obsoletos.
• Correlación web-vitals ↔ conversiones/fallos.

13) SDK cliente: requisitos

Light footprint, buffer offline, inicialización diferida.
Ajustes: sampling, max batch size, max queue age, privacy-mods (no-PII).
Protección: firma del paquete/anti-tamper, ofuscación de claves.
Actualización: banderas de características para desactivar eventos ruidosos.

14) Edge-capa y protección

Rate limit, WAF, validación schema, compresión (gzip/br).
Token bucket por cliente; anti-replay ('request _ id', TTL).
Eliminación de IP y UA → normalización/enriquecimiento fuera del payload «crudo».

15) Integración con el transportador de datos

Bronce: payload crudo irreversible-aditivo (para el forensic).
Silver: tablas normalizadas con dedoop/enriquecimiento.
Oro: escaparates para BI/AML/RG/producto.
Linaje entre eventos e informes; versiones de transformaciones.

16) Análisis de calidad del cliente

Tasa de «clientes silenciosos» (no hay eventos por hora N).
Anomalías de «tormenta» (mass duplicate/burst).
Proporción de «SDK obsoletos» por versión y plataforma.

17) Procesos y RACI

R: Data Platform (ingest/bus/validadores), App Teams (instrumentación SDK).
A: Head of Data/Architecture.
C: Compliance/DPO (PII/retention), SRE (SLO/incidentes).
I: BI/Marketing/Riesgo/Producto.

18) Hoja de ruta para la implementación

1. Taxonomía de eventos v1 + diagrama JSON para 6-8 tipos.

2. SDK (Web/Android/iOS) с batch и sampling; Edge `/telemetry/batch`.

3. Kafka + capa de Bronce; validadores básicos y dedoup.

4. El dashboard ingest lag/completeness, alertas en el drop/validador.

• OTel Collector, correlación de trais; Normalización de plata y reglas DQ.
• Endpoints regionales (EEA/UK), privacy-mods, procedimientos DSAR/RTBF.
• Mapa de las versiones SDK, actualizaciones auto-rollout por anillos.

• Exactly-Once en streaming, Feature Store conectividad, antifraude en línea feeds.
• Rule-as-Code para circuitos y validadores, simulación de cambios (impact analysis).
• Optimización de costos: sampling adaptativo, Z-order/clustering en el lago.

19) Check-list de calidad antes del lanzamiento

• Se han rellenado los campos de esquema obligatorios y los tipos correctos.
• 'trace _ id '/' request _ id '/' session _ id' están presentes.
• SDK admite batch, retry, sampling.
• Edge valida el esquema y limita el tamaño del payload.
• Se incluyen filtros de privacidad y tokenización de campos sensibles.
• SLO/alertas y dashboards personalizados.
• Documentación para dominios (ejemplo de evento, owner, SLA).

20) Errores frecuentes y cómo evitarlos

Eventos crudos sin esquemas: escriba registro y validación CI.
Sin idempotencia: requiere 'event _ id' y almacena las ventanas del dedup.
Mezcla de PII y análisis: separar los muppings, enmascarar los campos.
Sin tracking: trace 'trace _ id' a través de gateway → servicios → eventos.
Volúmenes no gestionados: aplique sampling/trrottling y cuotas de budget.
Global endpoint sin regiones: use regionalización y residencia de datos.

21) Glosario (breve)

OpenTelemetry (OTel) es un estándar abierto para tracks/métricas/registros.
Outbox - Publicación transaccional de eventos de dominio.
DLQ es una cola de mensajes «rotos».
Sampling: selecciona parte de los eventos para reducir el volumen.
Data Residency - Almacenar datos en la jurisdicción correcta.

22) Resultado

La telemetría bien diseñada es un arreglo, no sólo un «envío de registros»: esquemas estrictos, identificadores acordados, privacidad predeterminada, transporte confiable, observabilidad y costo económico. Siguiendo este artículo, obtendrá un flujo constante de eventos listos para el análisis, el cumplimiento y el aprendizaje automático con SLO predecibles.