import pandas as pd

Cheat sheet per il real-time analytics

Prima di mettere in produzione una pipeline real-time, il team ha bisogno di una checklist che non dimentichi i punti scomodi: event time, late data, idempotenza, backpressure, freshness, costi e owner degli alert. Questa scheda serve a fare review rapide senza ridurre l’architettura a slogan.

Come usare la scheda

Usala come strumento da review: scorri le domande prima di approvare ingestion, trasformazioni, viste, dashboard e alert. Se una voce non ha una risposta chiara, non è un dettaglio da rimandare, è un punto in cui la pipeline può produrre velocemente un errore.

Conviene avere in testa la sequenza di lavoro, dove ogni passaggio chiarisce il costo di una decisione sbagliata.

Step	Question to ask	Expected output
Decision	Che cosa cambia se la pipeline funziona?	Scelta esplicita
Signal	Quale dato osservabile riduce l’incertezza?	Metrica o evento
Baseline	Rispetto a cosa interpretiamo il risultato?	Credible comparison
Vincolo	Che cosa può falsare la lettura?	Assunzione da dichiarare
Action	Quale passo operativo segue?	Raccomandazione controllabile

In un progetto reale la pipeline non vive isolata. È parte di un sistema più ampio fatto di decisioni, dati disponibili, vincoli tecnici, incentivi organizzativi e qualità dell’esecuzione. La prima domanda non è “quale metrica calcolo?” ma quale decisione dovrà essere presa grazie a questa analisi. Una dashboard o una query hanno valore solo se riducono incertezza decisionale; se non cambiano una scelta, sono documentazione o teatro analitico.

Reference stack

App/Sensori → Kafka → ClickHouse (Kafka Engine) → Materialized Views → Dashboard (Grafana)

Lo stack tipico mette insieme Kafka per la durability e ClickHouse per la velocità, con materialized view a strati che pre-aggregano i dati e alert dinamici che evitano di affogare nei falsi positivi. Conviene tenere separate le dashboard operative da quelle analitiche, e ricordare che se il dato può aspettare un’ora il batch resta più economico.

Essential ClickHouse commands

-- Tabella Kafka (ingestione)
CREATE TABLE kafka_events (...) ENGINE = Kafka
SETTINGS kafka_broker_list='...', kafka_topic_list='...',
         kafka_group_name='...', kafka_format='JSONEachRow';

-- Materialized View in cascata
CREATE MATERIALIZED VIEW mv_1min ENGINE = SummingMergeTree()
ORDER BY (minute, type) AS SELECT toStartOfMinute(time) AS minute,
       type, count() AS cnt FROM kafka_events GROUP BY minute, type;

-- Query con FINAL per deduplicazione
SELECT * FROM customers FINAL WHERE id = 123;

-- Top N ultimi 5 minuti
SELECT type, count() FROM events WHERE time >= now() - INTERVAL 5 MINUTE
GROUP BY type ORDER BY count() DESC LIMIT 10;

Scelta dell’ORDER BY

È la decisione più importante in ClickHouse, perché determina l’ordine fisico dei dati su disco e quindi la velocità delle query.

If main query is...	Optimal ORDER BY
Filter by user	(user_id, event_time)
Aggregation by event type	(event_type, event_time)
Pure time series	(event_time, event_type)
JOIN with other tables	Dimension PK as first field

Batch o stream

La scelta tra batch e stream dipende dall’urgenza della decisione che il dato deve supportare.

Batch	Stream
Monthly reports	Fraud detection
ML model training	Operational dashboards
Financial reconciliations	In-session personalization
Data quality audit	Automatic alerting

Anti-pattern da evitare

Alcuni errori ricorrenti vanno bloccati in review. Usare SELECT * su ClickHouse forza la lettura di tutte le colonne. Le soglie statiche su metriche con volumi variabili producono allarmi inutili, e vanno sostituite con una baseline adattiva. Una materialized view senza un ORDER BY ottimizzato resta lenta quanto la query grezza. Un alert senza un’azione richiesta è di fatto un log, non un alert.

Real case: Netflix and the discipline of metrics

Netflix è un esempio utile perché ha costruito molte decisioni di prodotto intorno a segnali comportamentali osservabili: completamento degli episodi, tempo di ricerca prima della riproduzione, abbandono dopo pochi minuti, ritorno nella settimana successiva, efficacia delle raccomandazioni. Il punto non è che ogni azienda debba copiare Netflix, ma che il dato non viene trattato come ornamento, bensì come infrastruttura decisionale.

Quando Netflix valuta una modifica all’esperienza, che sia una nuova riga di raccomandazioni, una diversa immagine di copertina o un algoritmo di ranking, non misura solo il click immediato. Misura anche segnali di qualità: l’utente guarda davvero il contenuto, torna nei giorni successivi, riduce il tempo speso a cercare. Questa disciplina impedisce di ottimizzare vanity metric che sembrano positive nel breve periodo ma erodono valore nel lungo. Lo stesso vale per ogni voce di questa scheda: ha valore solo se collegata a un outcome.

Esempio SQL: una vista di controllo

Il pattern seguente è volutamente generico ma eseguibile nella maggior parte dei warehouse moderni. Serve a creare una base analitica con metrica, segmento e finestra temporale, così da confrontare periodi e gruppi senza riscrivere la logica ogni volta.

WITH base_events AS (
  SELECT
    user_id,
    account_id,
    event_type,
    event_time,
    DATE_TRUNC('week', event_time) AS week,
    source,
    device_type
  FROM events
  WHERE event_time >= CURRENT_DATE - INTERVAL '180 days'
    AND user_id IS NOT NULL
),
weekly_user_metrics AS (
  SELECT
    week,
    user_id,
    COALESCE(source, 'unknown') AS source,
    COALESCE(device_type, 'unknown') AS device_type,
    COUNT(*) AS total_events,
    COUNT(DISTINCT DATE(event_time)) AS active_days,
    COUNT(DISTINCT event_type) AS event_diversity,
    MAX(CASE WHEN event_type IN ('purchase', 'subscribe', 'activation') THEN 1 ELSE 0 END) AS reached_key_outcome
  FROM base_events
  GROUP BY week, user_id, source, device_type
)
SELECT
  week,
  source,
  device_type,
  COUNT(DISTINCT user_id) AS users,
  ROUND(AVG(active_days), 2) AS avg_active_days,
  ROUND(AVG(event_diversity), 2) AS avg_event_diversity,
  ROUND(AVG(reached_key_outcome) * 100, 2) AS key_outcome_rate
FROM weekly_user_metrics
GROUP BY week, source, device_type
ORDER BY week, source, device_type;

Questa query non è la risposta finale. Crea una superficie di osservazione fatta di trend, segmenti, differenze tra canali e variazioni nel tempo, da cui l’analista formula ipotesi più precise.

Esempio Python: stabilità e anomalie

Una metrica utile deve essere abbastanza stabile da orientare decisioni e abbastanza sensibile da segnalare cambiamenti reali. In Python possiamo controllare variazioni anomale settimana su settimana.

# df contiene: week, segment, users, key_outcome_rate
# key_outcome_rate espresso in percentuale, es. 12.4

df = df.sort_values(['segment', 'week']).copy()
df['previous_rate'] = df.groupby('segment')['key_outcome_rate'].shift(1)
df['wow_change_pp'] = df['key_outcome_rate'] - df['previous_rate']
df['rolling_mean'] = df.groupby('segment')['key_outcome_rate'].transform(
    lambda s: s.rolling(4, min_periods=2).mean()
)
df['rolling_std'] = df.groupby('segment')['key_outcome_rate'].transform(
    lambda s: s.rolling(4, min_periods=2).std()
)
df['z_score'] = (df['key_outcome_rate'] - df['rolling_mean']) / df['rolling_std']

anomalies = df[df['z_score'].abs() >= 2].sort_values('z_score')
print(anomalies[['week', 'segment', 'key_outcome_rate', 'wow_change_pp', 'z_score']])

Il valore di questo controllo è pratico: evita di reagire a ogni oscillazione casuale e segnala quando una variazione merita un’indagine. Durante una go-live review questo tipo di controllo, insieme alla checklist, blocca un rilascio quando per esempio mancano gli owner degli alert o una strategia per gli eventi tardivi.

Errori comuni

Il primo errore è lavorare su dati aggregati troppo presto, perché una media globale può nascondere due segmenti che si muovono in direzioni opposte. Il secondo è non controllare la qualità del dato: eventi duplicati, tracking incompleto, timezone incoerenti e cambi di definizione producono conclusioni false. Il terzo è confondere correlazione e causalità. Se gli utenti che usano una feature convertono di più, non significa che la feature causi la conversione: potrebbero usarla perché erano già più motivati. Per ridurre questi rischi, ogni analisi dovrebbe includere almeno tre controlli: una definizione esplicita della metrica, un confronto per segmento e una verifica contro un periodo precedente o un gruppo di controllo.

Summary

Lo stack real-time mette Kafka per la durability e ClickHouse per la velocità, con materialized view a strati che pre-aggregano e alert dinamici che evitano i falsi positivi. Le dashboard operative restano separate da quelle analitiche, e se il dato può aspettare un’ora il batch costa meno. La forma corretta del lavoro resta fatta di decisione, segnale, baseline, rischio e azione, e ogni voce della scheda serve solo se rende più affidabile uno di questi passaggi.