Exploitation d'Argos

📑 Table des matières

Supervision
Sauvegardes
Mises à jour
Dépannage

Supervision

Sondes de santé

Point d'accès	Port	Usage
`GET /healthz`	4000 (API, workers), 3100 (dashboard)	Vivacité du processus
`GET /readyz`	4000	Disponibilité : base de données et Redis joignables (`503` sinon)
`GET /api/v1/health`	3009 (Odin)	Santé d'Odin (base et Redis)

Zeus n'a pas de port HTTP. Son démarrage se lit dans ses journaux (BullMQ worker ready).

Dashboard

Page	Contenu
Vue d'ensemble	Compteurs, débit par étape sur 24 h, état des documents, connexions, erreurs récentes
Métriques	Sur 24 h, 7 ou 30 jours, par site. Durées médiane et 95e centile par étape et chez Odin, attente en file, durée et volume des synchronisations, appels et latence MCP par outil, échecs par raison, documents par type
Traitements	Files de traitement, capacité d'extraction utilisée, journal des événements
Traitements en échec	Documents en échec par raison, évolution sur 30 jours, relance ou abandon
Paramètres › Système	État de la base, de Redis, du stockage et d'Odin

Métriques Prometheus

GET /metrics sur le port 4000 de l'API, au format texte Prometheus. Ce point d'accès n'est pas authentifié : ne l'exposez pas publiquement. Les valeurs sont globales, identiques sur chaque pod : collectez-les sur un seul pod de l'API.

Métrique	Description
`spmcp_items_total{kind}`	Éléments indexés par type (fichier, page, dossier, sous-fichier)
`spmcp_stage_items{stage,status}`	Étapes de traitement par statut
`spmcp_queue_jobs{queue,state}`	Tâches par file et par état
`spmcp_odin_inflight{lane}`	Documents en cours d'extraction
`spmcp_odin_queue_waiting`	Demandes en attente chez Odin
`spmcp_dead_letters_open`	Traitements en échec à traiter

Alertes suggérées :

spmcp_dead_letters_open en hausse ;
/readyz en échec ;
spmcp_odin_inflight saturé alors que spmcp_odin_queue_waiting ne diminue plus : Odin ou Zeus arrêté.

Sauvegardes

Élément	Sauvegarde	Remarque
PostgreSQL (bases `argos` et `odin`)	Sauvegarde standard (`pg_dump`, PITR)	Source de vérité : configuration, index, contenu extrait, graphe
`ENCRYPTION_KEY`	Coffre-fort	Sans elle, les secrets stockés (mots de passe SharePoint, keytabs, clés LLM) sont illisibles
Stockage S3	Réplication ou sauvegarde du bucket	Les fichiers peuvent être retéléchargés depuis SharePoint ; les conserver évite de refaire les extractions
Redis	Facultative	Sa perte n'entraîne aucune perte de données : les files sont reconstruites depuis la base

Docker Compose :

docker compose exec -T postgres pg_dump -U argos -Fc argos > argos-$(date +%F).dump
docker compose exec -T postgres pg_dump -U argos -Fc odin  > odin-$(date +%F).dump

Mises à jour

Lire les notes de version. Utilisez la même version pour argos-serveur et argos-front-end.
Sauvegarder la base PostgreSQL.
Déployer :
- Docker Compose : ARGOS_VERSION=<version> dans .env, puis docker compose pull && docker compose up -d --wait ;
- Kubernetes : mettez à jour les images des Deployments, puis kubectl -n argos apply -f argos-serveur.yaml -f argos-front-end.yaml.

Les migrations de la base s'appliquent automatiquement (service migrate, ou initContainer de l'API). Les traitements en cours reprennent après le redémarrage des workers.

Pour retraiter les documents après une mise à jour d'Odin ou un changement de modèle :

un site entier : page de la connexion › Retraiter (nouveau traitement Odin de tout le site) ;
un document : page du document (Documents) › Relancer l'étape voulue (téléchargement, extraction, graphe, embeddings).

Dépannage

Symptôme	Cause probable	Action
Connexion au dashboard refusée après Devana	URI de redirection incorrecte	Le client OAuth doit déclarer exactement `<PUBLIC_URL>/auth/callback` ; vérifier `PUBLIC_URL`
Adresse MCP affichée incorrecte	`PUBLIC_URL` ne correspond pas à l'URL publique	Corriger `PUBLIC_URL` et redémarrer l'API
`Tester la connexion` échoue en 401	Identifiants, domaine ou méthode d'authentification	Vérifier le compte de service, essayer `DOMAINE\compte` (NTLM), vérifier la configuration Kerberos (URL de test)
Erreur de certificat vers SharePoint	Autorité interne non reconnue	Coller le certificat de l'autorité (PEM) dans la connexion
Documents bloqués « en attente » d'extraction	Odin ou Zeus arrêté, Redis ou bucket différent	Vérifier les pods Odin et Zeus, et que Redis (base 0) et le bucket sont ceux d'Argos
Images et pages scannées sans contenu	Modèle de vision non configuré	Renseigner `LLM_VISION_*` dans la configuration de Zeus
Recherche sémantique ou graphe vides	Modèles non affectés	Paramètres › Modèles (LLM) : affecter les rôles embeddings et graphe
Un agent attend puis échoue sur `read_file`	Délai du reverse proxy trop court	Autoriser au moins 960 s sur `/mcp` (voir les guides d'installation)
`403` sur le serveur MCP	Clé API d'un autre serveur (principal ou espace)	Utiliser une clé créée pour ce serveur
Documents en échec	Voir la raison dans Traitements en échec	Corriger la cause (droits, format, taille), puis relancer par raison, site ou sélection
Index incohérent ou changement d'instance Odin	—	Page de la connexion › Configuration › Réinitialiser l'index, puis nouvelle extraction complète depuis SharePoint

Journaux :

Docker Compose : docker compose logs -f serveur-api serveur-worker odin zeus.
Kubernetes : kubectl -n argos logs deploy/argos-worker -f.

Le niveau de détail se règle avec LOG_LEVEL (debug pour un diagnostic).