Supervision et alertes

Cette page décrit les signaux Prometheus de la plateforme, les règles d'alerte et la réception des alertes par le Control Plane.

Métriques

Source	Exposition	Familles
API (eai.main)	GET /metrics, jeton porteur EAI_METRICS_TOKEN	eai_http_*, eai_gateway_requests_total, eai_gateway_tokens_total, eai_gateway_cost_total, eai_policy_decisions_total, eai_quota_rejections_total, eai_security_events_total, eai_alerts_received_total
Worker (python -m eai.worker)	port EAI_WORKER_METRICS_PORT (9464)	eai_worker_job_duration_seconds, eai_worker_job_failures_total, eai_worker_job_last_success_timestamp_seconds, eai_worker_last_tick_timestamp_seconds, jauges globales
Media worker (python -m eai.media_worker)	port EAI_MEDIA_WORKER_METRICS_PORT (9465)	eai_media_worker_jobs_total, eai_worker_last_tick_timestamp_seconds{worker="media_worker"}

Les compteurs du Model Gateway sont alimentés par l'enregistrement de l'usage (gateway.record) et par les échecs (gateway.audit_failure). Chaque décision de politique enregistrée incrémente eai_policy_decisions_total, chaque rejet de quota eai_quota_rejections_total.

Les jauges globales sont calculées depuis la base par le job gauges du worker (l'API a plusieurs réplicas) : eai_runs_active, eai_heartbeat_stale_runs, eai_kill_switches_active{kind}, eai_media_queue_depth, eai_media_queue_oldest_age_seconds. Le job verify_chain (toutes les EAI_WORKER_VERIFY_CHAIN_INTERVAL_SECONDS, une heure par défaut) recalcule la chaîne d'audit de chaque tenant et publie eai_audit_chain_valid{tenant} et eai_audit_chain_broken_tenants. Une chaîne cassée écrit l'événement d'audit et de sécurité audit.chain_verify_failed et le transmet au SIEM.

Le label des jobs du worker est job_name : job est réservé par Prometheus à la cible.

Accès à /metrics

Hors dev et test, EAI_METRICS_TOKEN (32 caractères minimum) est exigé par le contrôle de démarrage. Sans l'en-tête Authorization: Bearer <jeton>, GET /metrics répond 401. Le chart Helm :

• le ServiceMonitor lit le jeton dans le secret global.monitoring.metricsTokenSecret (par défaut le secret du Control Plane, clé EAI_METRICS_TOKEN) ;
• un PodMonitor collecte le worker sur le port metrics ;
• les CiliumNetworkPolicy n'ouvrent ces ports qu'au namespace de supervision.

Règles d'alerte

Les règles sont dans deploy/observability/prometheus/rules/eai-slo-cost.yaml et leur copie deploy/observability/k8s/prometheusrule-eai.yaml. Le groupe eai-operations ajoute :

Alerte	Condition
EaiAuditChainBroken	au moins un tenant dont la chaîne d'audit est cassée
EaiAuditChainNotVerified	aucune vérification réussie depuis 3 heures
EaiKillSwitchActive	un kill switch fournisseur, modèle ou tenant actif depuis 5 minutes
EaiMediaQueueBacklog	plus de 100 jobs médias en file ou le plus ancien a plus de 15 minutes
EaiWorkerDown	worker absent ou dernier tick de plus de 5 minutes
EaiWorkerJobFailing	plus de 2 échecs d'un job en 30 minutes
EaiSecurityEventsSpike	taux d'événements de sécurité trois fois supérieur à la moyenne du jour

Le test tests/test_platform_metrics.py vérifie que chaque métrique citée par les règles et les tableaux de bord est une famille déclarée, et tests/test_observability_signals.py que chaque helper de eai.metrics est appelé par le code.

Réception des alertes

Alertmanager envoie toutes ses alertes (receiver default compris) à POST /v1/incidents/alerts avec une clé API de service portant explicitement le scope incidents:alerts (ou incidents:* ; le joker global * d'une session interactive ne compte pas, un lecteur ne peut donc pas ouvrir d'incident) ou le rôle alert_receiver, lue par http_config.authorization.credentials_file dans le secret eai-alert-receiver (clé api-key).

• Une alerte firing ouvre un incident de catégorie alert ou met à jour l'incident ouvert de même empreinte.
• Une alerte resolved résout cet incident.
• Chaque changement est audité (incident.alert.open, incident.alert.update, incident.alert.resolve) et transmis au SIEM.

Rattachement au tenant : les alertes arrivent dans le tenant de la clé (tenant d'exploitation). Les alertes de plateforme, sans label tenant, y arrivent donc toujours. Un label tenant=<uuid> n'est suivi que si la clé appartient à un administrateur de plateforme.

Chaîne d'audit cassée

1. Identifier le tenant dans eai_audit_chain_valid == 0 ou dans l'incident ouvert.
2. GET /v1/audit/verify sur ce tenant donne la séquence et la raison (hash mismatch, prev_hash mismatch, sequence gap).
3. Traiter comme un incident de sécurité : geler les accès en écriture à la base et comparer avec l'export WORM.