Telemetria e coleta de eventos

1) Atribuição e princípios

• Fluxo único e previsível de eventos para analistas, antifrode, RG, complacência e ML.
• Traçado de passagem (user/sessions/request/trace) e reprodutividade.
• Minimização do PII e conformidade com a privacidade.

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

2) Taxonomia de eventos

Pagamentos: 'payment. deposit`, `payment. withdrawal`, `payment. chargeback`.
Jogos: 'game. session_start/stop`, `game. bet`, `game. payout`, `bonus. applied`.
Personalizado: 'auth. login`, `profile. update`, `kyc. status_changed`, `rg. limit_set`.
Operação: 'api. request`, `error. exception`, `release. deploy`, `feature. flag_changed`.
Complaens: 'aml. alert_opened`, `sanctions. screened`, `dsar. requested`.

Cada tipo tem um dono (domain owner), um padrão e um SLO de frescura.

3) Esquemas e 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"}
}

Evolução dos circuitos: versões semânticas; backward-compatível - adicione os campos nullable; breaking - apenas em uma nova versão ('/v2 ') com um período de gravação dupla.

4) Ferramentas: onde e como

4. 1 Cliente (Web/Mobile/Desktop)

Telemetria SDK com bufê local, envio batch, retratos exponenciais.
Eventos automáticos: visitas, cliques, visibilidade de blocos, web-vitals (TTFB, LCP, CLS), erros de JS.
Identificadores: 'device _ id' (sustentável, mas privado), 'suisse _ id' (atualizado), 'user. pseudo_id`.
Proteção contra «ruídos»: deadup por «event _ id», trottling, cliente-side sampling.

4. 2 Servidor/Backend

Os embrulhos de logger/trainer (OpenTelemetry) → o emit de eventos de domínio.
É obrigatório cadastrar 'trace _ id' de edge/gateway em todos os serviços de downstream.
Outbox-pattern para publicação transacional de eventos de domínio.

4. 3 Provedores/terceiros

Conectores (PSP/KYC/estúdios) com normalização para sistemas hosts; adaptadores de versões.
Assinatura/verificação de integridade payload, perímetro de jornalismo (ingest check).

5) OpenTelemetry (OTel)

Trailers: Cada pedido recebe 'trace _ id'; associamos logs/eventos através de 'trace _ id '/' span _ id'.
Logi: Usemos OTel Logs/conversores; marcas do ambiente 'service. name`, `deployment. env`.
Métricas: RPS/latency/error-rate de serviços, métricas de negócios (GGR, conversão).
Colector: ponto único de recepção/tampão/exportação para Kafka/HTTP/gráfico. uma pilha.

6) Identificadores e correlação

'event _ id' é exclusividade e idempotidade.
`user. pseudo _ id 'é um pseudônimo estável (mupping separado e restrito).
'sessions _ id', 'request _ id', 'trace _ id', 'device _ id' - são obrigatórios para análise de borda.
Compatibilidade de ID no nível de entrada API e SDK.

7) Sementear e controlar o volume

Regras: per-event-tipo, per-market, dinâmica (adaptável) por carga.
Eventos precisos de pagamentos/complicações/incidentes não são semeados.
Eventos analíticos: 10% a 50% são permitidos com balanças corretivas nas vitrines.
Server-side downsampling: é válido para alta-frequency métricas.

8) Privacidade e complacência

Minimize o PII: Torneie PAN/IBAN/email; O IP → geo/ASN no ingest.
Regionalização: Envie para engest-endpoint regionais (EEA/UK/BR).
DSAR/PTBF: suporte para ocultação seletiva de projeções; registro de transações legais.
Políticas de armazenamento: prazos por tipo (analista mais curto, regulatório mais longo); Legal Hold.

9) Transporte e tampão

Cliente → Edge: HTTPS (HTTP/2/3), 'POST/telemetry/batch' (até 100 eventos).
Edge → Shina: Kafka/Redpanda com partilha por 'user. pseudo_id`/`tenant_id`.
Formatos: JSON (ingest), Avro/Protobuf (pneu), Parquet (lake).
Confiabilidade: retrai com jitter, DLQ, poison-pill isolamento.

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

10) Confiabilidade e idempotação

Cliente-generated 'event _ id' + deadup de servidor por '(event _ id, fonte)'.
Outbox em serviços, Excactly-Once-semântica em streaming (keyed state + dedupe).
Ordem dentro da chave: Particionamento por 'user/sessions'.
Controle de tempo: NTP/PTP, deriva válida (por exemplo, ≤ 200 ms), 'received _ at' no servidor.

11) Qualidade da telemetria (TQ) e SLO

Completeness: ≥ 99. 5% dos eventos de tipos críticos por T.

Freshness: p95 atrasos de entrega até Silver ≤ 15 min

Cortness: circuitos de validade ≥ 99. 9%, drop-rate < 0. 1%.
Trace coverage: taxa de solicitação com 'trace _ id' ≥ 98%.
Costa/GB: Orçamento-alvo para ingest/armazenamento por domínio.

12) Observabilidade e dashboards

• Ligingest (p50/p95) por origem e região.
• Completeness por tipo de evento e mercado.
• Erros de validação de circuitos/oversized-payloads.
• Mapa de versões SDK e porcentagem de clientes obsoletos.
• Correlação web-vitals ↔ conversão/falhas.

13) Clientes SDK: requisitos

Mexprint leve, buffer offline, inicialização adiada.
Configurações: sampling, max batch size, max queue age, moda de privacidade (no-PII).
Segurança: assinar pacote/anti-tamper, revogar chaves.
Atualização: bandeiras de função para desativar eventos ruidosos.

14) Camada Edge e proteção

Rate limit, WAF, schema validation, compressão (gzip/br).
Token bucket por cliente; anti-replay ('request _ id', TTL).
Levantamento de IP e UA → normalização/enriquecimento fora do payload «cru».

15) Integração com a linha de montagem de dados

Bronze: payload cru irreversível e suplementar (para forense).
Silver: tabelas normalizadas com dedução/enriquecimento.
Gold: vitrines para BI/AML/RG/produto.
Linage entre eventos e relatórios; versões de transformações.

16) Analista de qualidade do cliente

Coeficiente de «clientes silenciosos» (sem eventos em N horas).
Anomalias «tempestade» (mass duplicate/burst).
Proporção de SDK obsoletos em versões e plataformas.

17) Processos e RACI

R: Plataforma de dados (ingest/pneu/validadores), App Teams (ferramenta SDK).
A: Head of Data/Architecture.
C: Compliance/DPO (PII/retenção), SRE (SLO/Incidentes).
I: BI/Marketing/Risco/Produto.

18) Mapa de trânsito de implementação

1. Taxonomia eventos v1 + circuitos JSON para 6-8 tipos.

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

3. Camada Kafka + Bronze; validadores básicos e dedups.

4. Dashboard ingest lag/completeness, alertas em drop/validador.

• OTel Colector, correlação de trade; A normalização silver e as regras DQ.
• Endpoints regionais (EEA/UK), moda privada, tratamentos DSAR/PHILBF.
• Mapa das versões SDK, atualizações auto-rollout por anéis.

• Exactly-Once em fluxos, Função Store conexão, fidas antifrod online.
• Rule-as-Code para esquemas e validadores, simulações de alterações (impact analysis).
• Otimização de custo: adaptativo sampling, Z-order/cluster em lake.

19) Folha de cheque qualidade antes do lançamento

• Os campos de esquema obrigatórios e os tipos corretos estão preenchidos.
• Estão presentes 'trace _ id '/' request _ id '/' direction _ id'.
• SDK suporta batch, retry, sampling.
• Edge valida o padrão e limita o tamanho do payload.
• Os filtros de privacidade e o torneamento de campos sensíveis estão ativados.
• São configurados SLO/alertas e dashboards.
• Documentação para domínios (exemplo de evento, owner, SLA).

20) Erros frequentes e como evitá-los

Eventos crus sem padrão: digite registry e validação CI.
Sem idempotação: exija 'event _ id' e guarde as janelas de dedução.
Mistura de PII e analistas: separe os muppings, disfarce os campos.
Falta de trainee: instale 'trace _ id' através de gateway → serviços → eventos.
Volumes fora de controle: aplique sampling/trottling e quotas budet.
Endpoint global sem regiões: use regionalização e data residency.

21) Glossário (breve)

OpenTelemetry (OTel) é um padrão aberto para trailers/métricas/logs.
Outbox - publicação transacional de eventos de domínio.
DLQ - fila de mensagens «batidas».
Sampling - selecionar parte dos eventos para reduzir o volume.
Data Residency - armazenamento de dados na jurisdição necessária.

22) Resultado

Telemetria bem projetada é um acordo, não apenas «envio de logs», como esquemas rigorosos, identificadores acordados, privacidade padrão, transporte confiável, observabilidade e custo econômico. Seguindo este artigo, você terá um fluxo sustentável de eventos, preparado para análise, compliance e aprendizado de máquina com SLO previsível.