Production Controls CVNTrade

Version : 1.0 Date : 2026-04-10 Statut : specification (pas encore implemente)

Ce document definit les controles de production pour le runtime CVNTrade. Il couvre le kill switch, l'observabilite, l'alerting, la detection de drift, le rollback et le deploiement progressif.

---

1. Kill Switch

Env var

CVN_KILL_SWITCH=1 arrete immediatement toute activite de trading. Valeur par defaut : 0 (trading actif).

Comportement attendu

Composant	Reaction a CVN_KILL_SWITCH=1
Runtime service (port 8030)	Health-check retourne {"status": "HALTED"}. Aucun signal n'est transmis a l'adapter. Sessions ouvertes passent en PAUSED.
Backtest engine	Skip du run avec log event=kill_switch_active action=skip.
DAG Airflow (pre-check)	Task check_kill_switch echoue avec message explicite. Le DAG ne s'execute pas.

Points d'implementation

• Runtime : verifier CVN_KILL_SWITCH au debut de chaque cycle de candle dans le session actor.
• Backtest : verifier dans _run_candle_loop_ldp() et _run_candle_loop_legacy() avant la boucle principale.
• DAGs : ajouter un ShortCircuitOperator en premier task de chaque launcher DAG.

Declenchement manuel

# Activer le kill switch
kubectl set env deployment/cvntrade-runtime CVN_KILL_SWITCH=1 -n cvntrade

# Desactiver le kill switch
kubectl set env deployment/cvntrade-runtime CVN_KILL_SWITCH=0 -n cvntrade

Via Helm (persistant) :

# infra/helm/cvntrade-runtime/values-prod.yaml
env:
  CVN_KILL_SWITCH: "1"

Log event (ADR-32)

Kill switch activated | event=kill_switch status=active source=manual

---

2. Observabilite

Point d'entree unique : Grafana (ADR-26).

Metriques Prometheus

Metrique	Type	Labels	Description
cvntrade_candle_latency_seconds	Histogram	crypto, stage	Latence par etape du pipeline (enrichment, inference, filters, execution)
cvntrade_pnl_total	Gauge	crypto	P&L cumule par crypto
cvntrade_pnl_drawdown_pct	Gauge	crypto	Drawdown courant en pourcentage
cvntrade_filter_block_total	Counter	crypto, filter	Nombre de signaux bloques par filtre (CUSUM, trend, confidence, meta, regime, cost, kelly)
cvntrade_filter_pass_total	Counter	crypto, filter	Nombre de signaux passes par filtre
cvntrade_prediction_distribution	Histogram	crypto, class	Distribution des probabilites BUY/HOLD
cvntrade_feature_psi	Gauge	crypto, feature	PSI par feature (mis a jour par batch quotidien)
cvntrade_prediction_psi	Gauge	crypto	PSI des predictions par rapport a la distribution de training
cvntrade_positions_open	Gauge	crypto	Nombre de positions ouvertes
cvntrade_signal_count_total	Counter	crypto, signal	Compteur de signaux BUY/HOLD emis

Dashboard Grafana : Production Controls

Panel	Source metrique	Visualisation
Kill Switch Status	cvntrade_kill_switch_active	Stat (vert/rouge)
P&L par crypto	cvntrade_pnl_total	Time series
Drawdown courant	cvntrade_pnl_drawdown_pct	Gauge avec seuils 5%/10%
Latence pipeline	cvntrade_candle_latency_seconds	Heatmap
Taux de blocage par filtre	cvntrade_filter_block_total / (block + pass)	Bar chart
Distribution predictions	cvntrade_prediction_distribution	Histogram
Feature drift (PSI)	cvntrade_feature_psi	Table triee par PSI desc
Positions ouvertes	cvntrade_positions_open	Stat par crypto

Log events (ADR-32)

Chaque action de controle produit un evenement structure :

event=position_opened crypto=BTCUSDC side=BUY size=0.15 confidence=0.72
event=position_closed crypto=BTCUSDC side=SELL reason=tp pnl=+1.2%
event=filter_blocked crypto=BTCUSDC filter=cusum candle_ts=2026-04-10T12:00:00Z
event=drift_detected crypto=BTCUSDC feature=rsi_14 psi=0.25 action=warn
event=kill_switch status=active source=auto trigger=drawdown_critical

---

3. Alerting

Seuils et severites

Signal	WARN	CRITICAL	Action WARN	Action CRITICAL
Drawdown	> 5%	> 10%	Notification Slack	Kill switch automatique
Feature drift (PSI)	> 0.2	> 0.3	Trigger retrain	Kill switch automatique
Prediction drift (PSI)	> 0.2	> 0.3	Trigger retrain	Kill switch automatique
Latence pipeline	> 2s	> 5s	Notification Slack	Notification PagerDuty
Exchange rate limit	> 80% utilisation	> 95% utilisation	Throttle (doublement du cooldown)	Pause des requetes 60s
Position age	> 2x horizon	> 3x horizon	Notification Slack	Force close
Health check failure	1 echec consecutif	3 echecs consecutifs	Log warning	Restart pod

Canaux d'alerte

Severite	Canal	Delai cible
WARN	Slack #cvntrade-alerts	< 1 min
CRITICAL	Slack #cvntrade-alerts + PagerDuty	< 30s

Implementation

Alerting via Grafana Alerting (unifie avec ADR-26) : - Alert rules definies dans le dashboard Production Controls - Contact points : Slack webhook + PagerDuty integration - Notification policies : route CRITICAL vers PagerDuty, WARN vers Slack uniquement

---

4. Drift Detection

Methode : PSI (Population Stability Index)

PSI mesure la divergence entre la distribution de reference (training) et la distribution courante (production).

PSI = SUM( (actual_pct - expected_pct) * ln(actual_pct / expected_pct) )

PSI	Interpretation	Action
< 0.1	Pas de changement significatif	Aucune
0.1 - 0.2	Changement modere	Monitoring renforce
0.2 - 0.3	Changement significatif	Trigger retrain (WARN)
> 0.3	Rupture de distribution	Kill switch (CRITICAL)

Perimetre

• Features : PSI calcule sur les top-20 features par importance (selon le modele XGBoost). Stocke dans cvntrade_feature_psi.
• Predictions : PSI calcule sur la distribution des probabilites BUY. Stocke dans cvntrade_prediction_psi.

Frequence

Timeframe	Frequence de calcul	Fenetre de reference
30m	Quotidien	Derniers 7 jours vs training set
5m	Toutes les 6h	Derniers 24h vs training set

Stockage

• Metriques temps reel : Prometheus (retention 15j)
• Audit log : fichier JSONL par crypto, un record par batch
• Format : {"ts": "...", "crypto": "...", "features": {"rsi_14": 0.12, ...}, "prediction_psi": 0.08, "action": "none"}
• Chemin : logs/drift/{crypto}_drift.jsonl

Distribution de reference

La distribution de reference est calculee a partir du training set et stockee comme artifact MLflow lors de l'entrainement. Elle est chargee par le runtime via CacheInterface.get_training_distribution().

---

5. Rollback Procedure

5.1 Rollback modele (< 5 min)

Quand : modele en production degrade (drift, performance, bug).

Procedure :

1. Identifier le modele N-1 dans MLflow :

   # Lister les versions du modele
   mlflow models list-versions --name "CVNTrade_XGBoost_BTCUSDC_SL0.5_TP1_H4"
   

2. Promouvoir N-1 en Production (ADR-42 : promotion atomique par crypto) :

   # Via MLflow CLI ou UI
   mlflow models transition-stage --name "CVNTrade_XGBoost_BTCUSDC_SL0.5_TP1_H4" \
     --version <N-1> --stage Production
   

3. Redemarrer le runtime pour forcer le rechargement :

   kubectl rollout restart deployment/cvntrade-runtime -n cvntrade
   

4. Verifier dans Grafana que le modele charge est bien la version N-1.

5.2 Rollback config

Quand : changement de configuration ayant degrade le comportement.

# Rollback Helm (source de verite pour la config runtime)
helm rollback cvntrade-runtime <revision> -n cvntrade

# Ou git revert si le changement est dans values-prod.yaml
git revert <commit-sha>
# Puis redeploy via CI

5.3 Feature flag : version override

CVN_MODEL_VERSION_OVERRIDE permet de forcer une version specifique du modele, independamment du stage MLflow.

kubectl set env deployment/cvntrade-runtime \
  CVN_MODEL_VERSION_OVERRIDE=42 -n cvntrade

Quand cette variable est definie, le runtime charge la version specifiee au lieu de la version Production. Log event :

Model version override active | event=model_override version=42 crypto=BTCUSDC

Pour retirer l'override :

kubectl set env deployment/cvntrade-runtime CVN_MODEL_VERSION_OVERRIDE- -n cvntrade

5.4 Etat des sessions

Les sessions sont event-sourced (ADR-41). Un rollback de modele n'affecte que les futures predictions. Les sessions en cours conservent leur historique complet et peuvent etre rejouees avec le nouveau modele si necessaire.

---

6. Staged Rollout

Etapes

Etape	Perimetre	Duree	Critere de passage
Shadow	1 crypto (UNI)	24-48h	Predictions loggees, pas d'execution. Comparison avec modele actif.
Canary	1 crypto (UNI)	24h minimum	Execution reelle, capital reduit (10% du capital cible).
Expansion	Groupe complet (ex: defi)	48h	Canary valide, metriques stables.
Full rollout	Toutes les cryptos	-	Expansion validee.

Shadow mode

Le nouveau modele tourne en parallele du modele actif. Il recoit les memes candles, produit des predictions, mais ne genere aucun ordre.

Env var : CVN_SHADOW_MODE=1

Metriques comparees : - Distribution des predictions (BUY rate, confidence moyenne) - Taux de filtrage par chaque filtre - P&L simule vs P&L reel du modele actif

Log event :

event=shadow_prediction crypto=UNIUSDC signal=BUY confidence=0.68 active_signal=HOLD

Canary

Procedure :

1. Promouvoir le nouveau modele sur UNI uniquement (ADR-42 : promotion atomique par crypto).
2. Configurer le capital canary :

   kubectl set env deployment/cvntrade-runtime \
     CVN_CANARY_CAPITAL_PCT=0.10 -n cvntrade
   

3. Monitorer 24h dans Grafana.

Criteres de succes canary :

Metrique	Seuil
Drawdown	< 5%
Latence pipeline	< 2s p95
Feature PSI	< 0.2
Nombre de trades	> 0 (le modele n'est pas muet)
Erreurs runtime	0

Full rollout

Apres validation canary :

1. Promouvoir le modele sur les cryptos du groupe une par une.
2. Attendre 1h entre chaque promotion pour verifier la stabilite.
3. Retirer les overrides canary :

   kubectl set env deployment/cvntrade-runtime CVN_CANARY_CAPITAL_PCT- -n cvntrade
   

Rollback en cas d'echec

A chaque etape, si un critere de succes echoue :

1. Activer le kill switch si CRITICAL.
2. Rollback modele (section 5.1).
3. Post-mortem avant nouvelle tentative.

---

References ADR

ADR	Sujet	Lien avec ce document
ADR-26	Grafana point d'entree unique	Dashboard Production Controls
ADR-30	Logs structures = interface stable	Format des log events de controle
ADR-32	Format event=name key=value	Tous les evenements de ce document
ADR-39	Runtime standalone	Kill switch dans le runtime service
ADR-41	Sessions event-sourced	Rollback sans perte d'etat
ADR-42	Promotion atomique par crypto	Canary et staged rollout
ADR-54	Adaptive Event Engine	Moteur d'evenements adaptatif pour les controles de production