Export analytique vers ClickHouse
Le job analytics_export du worker (python -m eai.worker, leader élu) copie les nouvelles lignes de eai.usage_events et eai.telemetry_spans (tous les tenants, contexte système) vers eai_finops.usage_events et eai_telemetry.spans. Il ne s'exécute que si EAI_CLICKHOUSE_URL est défini ; sinon il se termine avec skipped.
Réglages
| Variable | Défaut | Rôle |
|---|---|---|
EAI_WORKER_ANALYTICS_EXPORT_SECONDS | 60 | intervalle du job |
EAI_ANALYTICS_EXPORT_BATCH | 5000 | lignes par insertion |
EAI_ANALYTICS_EXPORT_MAX_BATCHES | 20 | insertions par source et par exécution |
EAI_ANALYTICS_EXPORT_LAG_SECONDS | 5 | les lignes plus récentes attendent l'exécution suivante (transactions en cours) |
EAI_CLICKHOUSE_USER / EAI_CLICKHOUSE_PASSWORD | utilisateur eai-writer (INSERT seul) | |
EAI_CLICKHOUSE_TABLE | eai_telemetry.spans | renommage éventuel de la table des spans (base.table strict) |
DDL
Les fichiers sql/clickhouse/ s'appliquent dans l'ordre numérique (001_usage_events.sql, 002_daily_rollups.sql, 003_telemetry_spans.sql) ; un fichier appliqué n'est jamais modifié, une évolution ajoute le numéro suivant. Côté PostgreSQL, V094__analytics_export.sql crée eai.analytics_export_watermarks.
Idempotence
Chaque source est lue dans l'ordre de sa clé monotone (updated_at, id pour l'usage, created_at, id pour les spans). Chaque lot porte un insert_deduplication_token dérivé de ses bornes : un lot rejoué n'est pas inséré deux fois. Les tables sont des ReplacingMergeTree(version) : une ligne réexportée (événement d'usage réconcilié) remplace la précédente. Le watermark n'avance qu'après une insertion réussie ; en cas d'échec il reste inchangé, l'erreur bornée (sans identifiants) est conservée dans last_error et l'exécution suivante rejoue le même lot (au moins une fois).
Reprise complète (backfill)
UPDATE eai.analytics_export_watermarks SET last_ts = NULL, last_id = NULL WHERE source = 'usage_events';
La source repart du début ; les doublons sont fusionnés par le ReplacingMergeTree (requêtes avec FINAL pour un résultat exact avant fusion).