Télémétrie et collecte d'événements

1) Désignation et principes

• Un flux d'événements unique et prévisible pour l'analyse, l'antifrod, RG, Complaens et ML.
• Trace de bout en bout (user/session/request/trace) et reproductibilité.
• Minimisation des IPI et respect de la vie privée.

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

2) Taxonomie des événements

Paiement : 'paiement. deposit`, `payment. withdrawal`, `payment. chargeback`.
Jeux : 'jeu. session_start/stop`, `game. bet`, `game. payout`, `bonus. applied`.
Personnalisé : 'auth. login`, `profile. update`, `kyc. status_changed`, `rg. limit_set`.
Opérations : 'api. request`, `error. exception`, `release. deploy`, `feature. flag_changed`.
Conformité : 'aml. alert_opened`, `sanctions. screened`, `dsar. requested`.

Chaque type a un propriétaire (domain owner), un circuit et un SLO de fraîcheur.

3) Régimes et contrats

• `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"}
}

Évolution des schémas : versions sémantiques ; backward-compatible - ajouter des champs nullables ; breaking - uniquement dans la nouvelle version ('/v2 ') avec une période d'enregistrement double.

4) Instrumentation : Où et comment

4. 1 Client (Web/Mobile/Desktop)

SDK de télémétrie avec tampon local, envoi de batch, retraits exponentiels.
Auto-événements : visites, clics, visibilité des blocs, web-vitals (TTFB, LCP, CLS), erreurs JS.
Identifiants : 'device _ id' (stable mais privé), 'session _ id' (mis à jour), 'user. pseudo_id`.
Protection contre les « bruits » : dedup par 'event _ id', trottling, side-client sampling.

4. 2 Serveur/backend

Les enveloppes de logger/tracer (OpenTelemetry) → les emites d'événements de domaine.
Le défilement obligatoire de 'trace _ id' de edge/gateway vers tous les services downstream.
Modèle Outbox pour la publication transactionnelle d'événements de domaine.

4. 3 Fournisseurs/tiers

Connecteurs (PSP/KYC/studio) normalisés aux circuits hôtes ; adaptateurs de version.
Signature/vérification de l'intégrité de payload, journal du périmètre (ingest audit).

5) OpenTelemetry (OTel)

Tracés : chaque requête reçoit 'trace _ id' ; on relie les logs/événements via 'trace _ id '/' span _ id'.
Logs : nous utilisons OTel Logs/convertisseurs ; les étiquettes d'environnement 'service. name`, `deployment. env`.
Métriques : RPS/latency/error-rate par service, métriques d'entreprise (GGR, conversion).
Collecteur : point de réception unique/tampon/exportation vers Kafka/HTTP/graphic. une pile.

6) Identifiants et corrélation

'event _ id 'est l'unicité et l'idempotence.
`user. pseudo_id' est une pseudonymisation stable (mapping séparé et limité).
« session _ id », « request _ id », « trace _ id », « device _ id » sont obligatoires pour l'analyse de bout en bout.
Cohérence de l'ID au niveau de la passerelle API et du SDK.

7) Semer et contrôler le volume

Règles : per-event-type, per-market, dynamique (adaptative) par charge.
Événements filmés avec précision : paiement/conformité/incidents - ne sont pas échantillonnés.
Événements analytiques : 10-50 % sont autorisés avec des poids correcteurs dans les vitrines.
Server-side downsampling : admettons les métriques de haute fréquence.

8) Vie privée et conformité

Minimiser le PII : Tokeniser le PAN/IBAN/email ; IP → géo-codes/ASN dans ingest.
Régionalisation : envoyer aux endpoints ingest régionaux (EEE/UK/BR).
DSAR/RTBF : soutien à la dissimulation sélective des projections ; Journal des opérations juridiques.
Politiques de conservation : délais par type (l'analyse est plus courte, la réglementation est plus longue) ; Legal Hold.

9) Transport et tampon

Client → Edge : HTTPS (HTTP/2/3), 'POST/telemetry/batch' (jusqu'à 100 événements).
Edge → Shina : Kafka/Redpanda avec un lot de 'user. pseudo_id`/`tenant_id`.
Formats : JSON (ingest), Avro/Protobuf (dans le bus), Parquet (dans le lac).
Fiabilité : retraits avec jitter, DLQ, isolation poison-pill.

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

10) Fiabilité et idempotence

Client-generated 'event _ id' + dedup serveur par '(event_id, source)'.
Outbox sur les services, Exactly-Once-sémantique dans les flux (état keyed + dedupe).
Ordre dans la clé : lot par 'user/session'.
Contrôle du temps : NTP/PTP, dérive valide (par exemple, ≤ 200 ms), 'received _ at'sur le serveur.

11) Qualité de télémétrie (TQ) et SLO

Completeness: ≥ 99. 5 % des événements de types critiques par T.
Freshness : p95 retard de livraison à Silver ≤ 15 min.
Correctness : schémas valides ≥ 99. 9%, drop-rate < 0. 1%.
Trace coverage : proportion de requêtes avec 'trace _ id' ≥ 98 %.
Cost/GB : budget cible pour ingest/stockage par domaine.

12) Observabilité et dashboards

• Lag ingest (p50/p95) par source et région.
• Completeness par type d'événements et de marchés.
• Erreurs de validation des schémas/oversized-payloads.
• Carte des versions SDK et pourcentage de clients obsolètes.
• Corrélation web-vitals ↔ conversion/échec.

13) SDK client : exigences

Footprint léger, buffer hors ligne, initialisation différée.
Paramètres : sampling, max batch size, max queue age, mode privacy (no-PII).
Protection : signature du paquet/anti-tamper, obstruction des clés.
Mise à jour : des drapeaux de fonction pour désactiver les événements bruyants.

14) Couche Edge et protection

Rate limit, WAF, schema validation, compression (gzip/br).
Token bucket par client ; anti-replay ('request _ id', TTL).
L'élimination de la PI et de l'AU → la normalisation/enrichissement en dehors du paiement « brut ».

15) Intégration avec le pipeline de données

Bronze : payload brut à ajout irréversible (pour forenser).
Silver : tables normalisées avec déduplication/enrichissement.
Gold : vitrines pour BI/AML/RG/produit.
Linage entre les événements et les rapports ; versions des transformations.

16) Analyse de la qualité du client

Taux de « clients silencieux » (pas d'événements en N heures).
Anomalies de la « tempête ».
Part des « SDK obsolètes » par version et plate-forme.

17) Processus et RACI

R : Data Platform (ingest/bus/validateurs), App Teams (outil SDK).
A: Head of Data/Architecture.
C : Conformité/DPO (PII/rétention), SRE (SLO/incidents).
I : BI/Marketing/Risque/Produit.

18) Feuille de route pour la mise en œuvre

1. Taxonomie des événements v1 + schémas JSON pour 6 à 8 types.

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

3. Couche Kafka + Bronze ; validateurs de base et dedup.

4. Dashboard ingest lag/completeness, alertes sur drop/validateur.

• Collecteur OTel, corrélation de trace ; Normalisation de l'argent et règles DQ.
• Endpoints régionaux (EEE/Royaume-Uni), mode privée, procédures DSAR/RTBF.
• Carte des versions SDK, auto-rollout mises à jour par anneau.

• Exactly-Once dans les flux, connectivité Feature Store, fides en ligne antifrod.
• Rule-as-Code pour les schémas et les validateurs, simulation de changement (impact analysis).
• Optimisation des coûts : sampling adaptatif, Z-order/clustering dans le lac.

19) Chèque de qualité avant la sortie

• Les champs obligatoires du schéma et les types corrects sont remplis.
• Il y a 'trace _ id '/' request _ id '/' session _ id'.
• SDK prend en charge batch, retry, sampling.
• Edge valide le schéma et limite la taille de payload.
• Les filtres de vie privée et la tokenisation des champs sensibles sont inclus.
• SLO/alerties et dashboards sont personnalisés.
• Documentation pour les domaines (exemple d'événement, owner, SLA).

20) Erreurs fréquentes et comment les éviter

Événements bruts sans schémas : entrez registry et CI-validation.
Pas d'idempotence : demandez 'event _ id' et gardez les fenêtres du dédoublement.
Mélange de PII et d'analytique : séparer les mappings, masquer les champs.
Pas de tracing : placez 'trace _ id' à travers la passerelle → les services → les événements.
Volumes non gérés : appliquez les quotas sampling/trottling et budget.
Endpoint global sans régions : utilisez la régionalisation et la résidence de données.

21) Glossaire (bref)

OpenTelemetry (OTel) est une norme ouverte pour les trajets/métriques/logs.
Outbox - Publication transactionnelle d'événements de domaine.
DLQ est une file de messages « battues ».
Sampling - sélection d'une partie des événements pour réduire le volume.
Data Residency - Stockez les données dans la bonne juridiction.

22) Résultat

La télémétrie bien conçue est un arrangement, pas simplement un "envoi de logs' : schémas rigoureux, identifiants cohérents, vie privée par défaut, transport fiable, observabilité et coût économique. En suivant cet article, vous recevrez un flux régulier d'événements, prêt pour l'analyse, la conformité et l'apprentissage automatique avec des SLO prévisibles.