Distribuzione dei segnali e delle metriche

(Sezione Ecosistema e Rete)

1) Obiettivo e area

• Un unico linguaggio di telemetria e contratti di dati.
• I canali QoS controllati sono la priorità dei segnali critici.
• SLI/SLO trasparenti e alerting prevedibile.
• Privacy, isolamento e risparmio di budget delle metriche.

2) Tassonomia dei segnali

1. Eventi aziendali: onboarding, depositi/pagamenti, eventi di gioco, attribuzione.
2. Le metriche sono latency/throughput/codice di errore, coda, uso CPU/RAM/IO.
3. Logi - Record strutturati di operazioni e errori.
4. Traccia: span di query/topic, correlazione hop-to-hop.
5. Stati di salute: synthetic propes, readover/liveness, heartbeat nodi.
6. Segnali di rischio/compilazione: KYC/KYB/AML successi, eventi di sanzione.

Ogni classe ha il proprio livello di criticità e criteri di conservazione/consegna.

3) Architettura di distribuzione

Raccoglitori Edge (SDK/Agenti) Ingress ( ) Shin (Kafka/Pulsar) Processori (stream-jobs) di Deposito (TSDB per le metriche, oggetto/invertebrato per i loghi/eventi, tracciatore) Vetrine/dashboard/alert.
Multi-tenantezza: namespace/tenant-id in chiave, singole quote/limits/ACL.
Segmentazione QoS: critica (P0), importante (P1), di sfondo (P2).
Egress: follower (Ops/BI/Third-party) tramite abbonamenti a top e materialization views.

4) Contratti e schemi (eventi/metriche/trailer)

4. 1 Eventi (semplificato, YAML)

yaml event:
id: uuid kind: business    ops    risk ts: timestamp    # ISO8601 tenant: string    # org_id/namespace source: string    # service/peer-id trace_id: string type: string     # deposit. created    payout. failed    probe. ok...
attrs: object # semantic fields (no PII)
severity: info    warn    error    critical qos: P0    P1    P2

4. 2 Metriche (OpenMetrics/OTLP)

Gauge/Counter/Historogram con etichette stabili (cardinalità limitata).
Identificatori: 'metric _ name {service, region, tenant, variante, route}'.
Istogrammi per latenza/dimensioni invece di p99 nel codice.

4. 3 Roulotte

I campi obbligatori sono «trace _ id», «span _ id», «part _ id», «service», «peer», «route», «qos».
Link tra domini (consumer/producer) e hop di rete (relay/bridge).

5) QoS e priorità

P0 (critico): pagamenti/rimborsi SLI, stati ponti/nodi, burn-rate SLO, spedizione rigorosa (acks, retries, idermotenza), minimi timeout.
P1 (essenziale): eventi alimentari/metriche di base, fornitura garantita all'interno dello SLO.
P2 - I fogli dettagliati, il debug del best-effort, possono essere drenati durante il sovraccarico.

Policy: code diverse, quote sui produttori, backpressure, rate-limits, deadup dì idempotency _ key ".

6) Cardinalità e budget delle metriche

Regola 6 etichette: massimo 6 chiavi per metrica, dizionari di valori fissi.
La cardinalità è 10 k file temporali/metrica/tenante.
Tracciabilità head-/tail-based downsampling metriche 10s→1m→5m→1h.
Quote: limiti di punti/s e byte/s per il tentante e per la classe QoS.
Schemi linter: rifiuta le metriche con etichette esplose (id, email, ip, ecc.).

7) Raccolta e consegna: push vs pull

Push (OTLP/StatsD/HTTP) - Flessibilità, client mobile/edge, canale P0.
Pull (Prometheus) - Infrastruttura interna, target prevedibili.
Ibrido: exporters→gateway→TSDB; federated scrapes per le regioni.
Trasporto: QUIC/HTTP/2, compressione, batch, TLS/mTLS, retrai con jitter.

8) SLI/SLO e alerting

8. 1 SLI base

Availability% endpoint/gateway,

Latency p50/p95/p99 su percorsi critici,

Error-rate (5xx/timeout/abort),

Delivery lag su pneumatico, Queue depth,

Freshness vetrine (ritardo ingest→serve).

8. 2 Esempi SLO

P0 pipelines: Availability ≥ 99. 95%, p99 latency ≤ 400 мс, Delivery lag p95 ≤ 2 с.

P1: Availability ≥ 99. 9%, Freshness p95 ≤ 3 minuti

P2: Freshness p95 ≤ 15 мин, no-page.

8. 3 burn-rate alert (esempio)

La finestra di 2 ore è «error _ budget _ burn 2 x».
La finestra di 6 ore è «error _ budget _ burn 1 x».
Combina con «queue _ lag» e «drop _ rate» P0.

9) Archivi e retenzioni

Metriche TSDB ad alta frequenza - 7-14 giorni Le unità sono 6-12 mes.
Eventi/logi: deposito caldo 7-30 giorni, freddo (oggetto) 6-24 mes.
Roulotte: sampling 1-10%; Salva span lenti/errati (tail-based).
Criteri di eliminazione/revisione per i PI e le richieste dei soggetti dati.

10) Privacy, sicurezza e isolamento

Riduzioni PII: Tornizzazione/alias dei campi, impedimento degli identificatori crudi nelle metriche.
mTLS/firma eventi, pinning chiavi produttori.
ACL/ABAC per argomenti/servizi/tenenti, singole chiavi per write/read.
Tenant sandboxing: separazione logica/fisica, limiti e rate-limit per tenant.
Controllo trail - Registri di accesso/modifica configure invariati.

11) Flussi di lavorazione (stream jobs)

Enrich: normalizzazione, geo/versione/classe di traffico.
Aggregate: finestre 10s/1m/5m, istogrammi, miniature quantiche.
Detect: anomalie (EWMA/ESD), deriva di distribuzione, picchi di coda.
Route: fan-out in vetrine/alert/webhoop dei partner.
Guard: «pulsante rosso» - throttling/kill-switch per origine/argomento.

12) Dashboard (layout)

Ops Core (ora/real-time): p95 latency, error-rate, delivery lag, queue depth, success-rate ingest.
Pipelines Health: freshness per pipeline, drop-rate, backpressure, burn-rate SLO.
Tenant Usage: file/secondi, byte/secondi, cardinalità, top labels.
Sicurezza/Compliance: mTLS gli stati, le chiavi di scadenza, la disponibilità, la revisione del PII.
Business Lens: conversione/pagamento/SLI ponte accanto alle metriche.

13) Esempi di configurazione

Classi di QoS e limiti (YAML)

yaml telemetry:
qos:
P0:
topics: [payout. sli, bridge. finality, gateway. availability]
delivery: guaranteed retry:
attempts: 3 backoff_ms: [100, 400, 800]
max_queue_lag_ms: 2000
P1:
topics: [product. events, api. metrics]
delivery: at-least-once sampling: 1. 0
P2:
topics: [debug. logs, verbose. traces]
delivery: best-effort sampling: 0. 1 quotas:
tenant_default:
metrics_points_per_sec: 50_000 logs_mb_per_hour: 500 traces_spans_sampled_pct: 5

Etichette metriche (criterio)

yaml metrics_policy:
allowed_labels: [service, route, code, region, tenant, version]
forbidden_labels: [user_id, email, ip, session_id]
max_label_value_count: 1000

Alert burn-rate

yaml alerts:
- name: "p0_error_burn_2h"
expr: burn_rate_p0_2h > 2 action: [page_oncall, open_incident]
- name: "queue_lag_p0"
expr: queue_lag_ms_p95 > 2000 action: [page_oncall]

14) Schemi di dati e query

Registro metriche (directory)

sql
CREATE TABLE metric_catalog(
name TEXT PRIMARY KEY,
unit TEXT, description TEXT,
labels JSONB, owner TEXT, qos TEXT, sla JSONB
);

Code e lega

sql
SELECT topic,
PERCENTILE_CONT(0. 95) WITHIN GROUP (ORDER BY lag_ms) AS lag_p95,
SUM(dropped) AS drops
FROM queue_metrics
WHERE ts >= now() - INTERVAL '24 hours'
GROUP BY topic;

Cardinalità per tentante

sql
SELECT tenant, metric_name, COUNT(DISTINCT series_id) AS series
FROM tsdb_series
WHERE day = current_date
GROUP BY tenant, metric_name
ORDER BY series DESC
LIMIT 50;

15) Processi e ruoli

Telemetry Owner - schemi/regole/quote, controllo della radicalità.
SRE/Ops - SLO, alert, incidenti, ridimensionamento.
Sicurezza/Compliance - chiavi, accessibilità, PII, verifiche.
Product/BI - vetrine KPI, analista, metriche A/B.
Tenants - Integrazione SDK corretta, conformità ai contratti.

16) Playbook incidenti

A. Esplosione di cardinalità

1. Unità auto produttore/metrico, 2) ritagliare «cattive» etichette, 3) aggregazione retro, 4) post mortem e regole linter.

B. Crescita queue lag P0

1. Includi la priorità, 2) espandere le partenze/notebook, 3) ridurre temporaneamente P2 sampling, 4) l'analisi dei colli di bottiglia.

C. Caduta delle vetrine Freshness

1. Passa al connettore di riserva, 2) attiva la modalità di degrado («ultimi finalizzati»), 3) informare i proprietari delle sorgenti.

D. Perdita di PII nelle metriche

1. Blocco immediato del flusso, 2) redaction su livello caldo, 3) notifica DPO/Compliance, 4) aggiornamento lenter/SDK.

E. Maschio 5xx/errori di traccia

1. Paige, 2) sampling tail-based per errori, 3) trace-diagnostica di percorso critico, 4) reimpostazione di rilascio/flag-flag.

17) Assegno-foglio di implementazione

1. Approva i contratti eventi/metriche/trailer e l'elenco delle etichette valide.
2. Imposta le classi QoS, i top/code, le quote e il budget delle metriche.
3. Configura ingest (push/pull), TLS/mTLS, retrai e idampotenza.
4. Abilita le cartelle delle metriche/eventi e i liner dei diagrammi.
5. Identificare SLI/SLO, burn-rate alert e escalation.
6. Costruisci dashboard Ops/Pipelines/Tenant/Security.
7. Esegui i test chaos di telemetria (perdita/jitter/spiegamenti).
8. Ringiovanire regolarmente cardinalità, retenze e costi di conservazione.

18) Glossario

QoS è una classe di qualità/priorità di consegna.
Freshness - Ritardo nella visualizzazione dei dati nella vetrina.
Burn-rate - la velocità di flusso del budget degli errori rispetto a SLO.
Cardinality è il numero di righe di metriche univoche (combinazioni etichette).
Tail-based sampling è un campione di tracciati lenti/errati.
Idempotency key è la chiave per la deduplicazione delle ripetizioni degli eventi.

Il risultato è che la distribuzione dei segnali e delle metriche non è semplicemente «raccogliere e mostrare grafici», ma una disciplina dei contratti, dei canali QoS e dei budget. Seguendo questo framework, l'ecosistema ottiene un'osservabilità prevedibile, resistente ai picchi, priva dei dati e utile per le soluzioni sia operative che aziendali.