Raccourcis clavier

Appuyez sur ← ou → pour passer d'un chapitre à l'autre

Appuyez sur S ou / pour rechercher dans la documentation

Appuyez sur ? pour afficher cette aide

Appuyez sur Échap pour masquer cette aide

Diagnostics et signalement

Ce chapitre rassemble les outils intégrés pour diagnostiquer un problème, signaler une anomalie et demander une fonctionnalité.

BesoinOutilRésultat
L'API répond-elle ?Routes de santé de forge-apiJSON d'état
Quel conteneur est tombé ?podman ps, podman logsÉtat et journaux
Quelle version tourne ?Champ sha de /api/v1/healthzSHA du commit déployé
Où en est le déploiement ?scripts/deploy/suivre-autodeploy.shDernier SHA, journal
Signaler une anomalieCourriel au supportÉchange tracé

Santé de la plateforme

forge-api expose trois routes de santé, sans authentification :

# Vivacité : répond 200 tant que le processus tourne (et indique la version)
curl -s http://localhost:3000/api/v1/healthz | jq .

# Disponibilité : vérifie PostgreSQL et Valkey
curl -s http://localhost:3000/api/v1/readyz | jq .

# Page d'état : une entrée par service (up, down ou degraded) avec sa latence
curl -s http://localhost:3000/api/v1/health/status | jq .

La réponse de healthz porte status, service, version et, quand l'environnement du processus la fournit (FORGE_GIT_SHA), le champ sha. Comparer ce sha au dernier commit est une façon simple de savoir si un déploiement est arrivé.

Résultat attendu : readyz répond 200 quand PostgreSQL et Valkey répondent, 503 sinon ; health/status répond 503 quand l'état global (overall) vaut down. En cas de 503, passez à la vérification manuelle des services ci-dessous.

Derrière le nom public, remplacez localhost:3000 par https://app.<domaine>.

Vérification manuelle des services

# État de tous les conteneurs
podman ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# PostgreSQL
podman exec forge-postgres sh -c 'pg_isready -U "$POSTGRES_USER"'

# Valkey
podman exec forge-valkey valkey-cli ping

# Qdrant (liste des collections)
curl -s http://localhost:6333/collections | jq .

# Ollama : modèles disponibles
podman exec forge-ollama ollama list

# OpenBao : état de scellement (code de sortie 2 = scellé)
podman exec forge-openbao bao status

# Passerelle MCP du plan client (port 8811)
curl -s http://localhost:8811/health

Résultat attendu : pg_isready répond « accepting connections » ; valkey-cli ping répond PONG ; la requête Qdrant liste les collections ; ollama list liste les modèles ; bao status rend le code de sortie 2 quand le coffre est scellé ; la passerelle répond à /health. Un échec renvoie à la section correspondante de Problèmes connus.

Les noms des conteneurs sont ceux des fichiers compose. En production, les services d'une unité Quadlet se pilotent avec systemd :

systemctl --user status forge-api.service

Ressources

# Mémoire et CPU par conteneur
podman stats --no-stream --format "table {{.Name}}\t{{.MemUsage}}\t{{.CPUPerc}}"

# Espace utilisé par Podman (images, conteneurs, volumes)
podman system df

# Espace disque de l'hôte
df -h

Journaux du backend

# Temps réel
podman logs -f forge-api

# 100 dernières lignes
podman logs --tail 100 forge-api

# Pour une unité Quadlet : journal systemd
journalctl --user -u forge-api.service -n 100

Les journaux de forge-api sont écrits en JSON par défaut, une ligne par événement, avec les champs du contexte de requête courant (LOG_FORMAT=pretty donne une sortie lisible ; TRACING_JSON n'est pas lue par ce binaire). Chaque requête porte un en-tête X-Request-ID (généré s'il manque) que la réponse renvoie : quand un utilisateur signale une erreur, demandez-lui cet identifiant pour retrouver la ligne.

Voir aussi Journaux.

Diagnostic de la passerelle MCP

Les routes MCP de forge-api exigent un utilisateur authentifié (en-tête Authorization: Bearer <jeton>, ou cookie de session) ; $TOKEN est le jeton rendu par la connexion, décrite dans Documentation Swagger :

# Ouvrir une session (la réponse porte l'en-tête Mcp-Session-Id)
curl -i -X POST http://localhost:3000/api/v1/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}},"id":1}'

# Consulter le catalogue des connecteurs
curl -s http://localhost:3000/api/v1/mcp/catalogue \
  -H "Authorization: Bearer $TOKEN" | jq .

Pour les erreurs renvoyées, voir Gestion des erreurs.

Suivre un déploiement

Le déploiement est tiré par l'hôte (minuteur toutes les 2 minutes). Depuis le poste d'un opérateur :

bash scripts/deploy/suivre-autodeploy.sh

Il affiche l'état du minuteur, le dernier SHA déployé et la fin du journal et de la construction, tous relatifs au front. Il ne lit pas l'état du backend : comparez le champ sha de /api/v1/healthz au commit attendu.

Signaler une anomalie

Écrivez à support@chatbotaurus.com en indiquant :

  • la description du problème ;
  • les étapes pour le reproduire ;
  • le comportement attendu et le comportement observé ;
  • les journaux pertinents, anonymisés ;
  • la version (sha de /api/v1/healthz) et l'environnement (production, plan client ou développement local) ;
  • l'identifiant X-Request-ID de la requête en cause, s'il est connu.

Attention : confidentialité

Avant de partager des journaux, retirez toute information sensible : clés d'API, jetons, mots de passe, adresses IP, données personnelles. Ne partagez jamais les clés de descellement OpenBao.

Une faille de sécurité se signale à security@chatbotaurus.com, pas par le canal ordinaire.

Demander une fonctionnalité

Écrivez à support@chatbotaurus.com avec le préfixe [Feature] dans l'objet et décrivez :

  • le cas d'usage ;
  • la solution proposée ;
  • les alternatives envisagées ;
  • l'impact sur la conformité UE, si applicable.

Voir aussi