Observabilité

# gateway.env — export telemetry to your OTLP collector
AIHUMMER_OTEL_ENDPOINT=http://otel-collector:4317

La capacité d'observabilité d'AiHummer a **deux surfaces**: la passerelle sert de **Prométhée `GET /metrics`** point de terminaison que vous pouvez interroger pour les bases, et il peut éventuellement **envoyer la télémétrie via OTLP** vers un point de terminaison OpenTelemetry que vous configurez. Gratter `/metrics` pour la surveillance de base ; pour les traces et les métriques riches, pointez AiHummer vers votre collecteur OTLP et visualisez les données avec les tableaux de bord Grafana inclus. > [!NOTE] > pprof (`/debug/pprof`) est **pas** exposé. ## Le Prométhée `/metrics` point de terminaison `GET /metrics` sert des métriques au format texte Prometheus sans configuration supplémentaire. Seules des jauges non sensibles sont exposées — informations sur la version, temps de fonctionnement du processus et durée d'exécution, état du pool de connexions à la base de données et une jauge de disponibilité ; aucune donnée de locataire, aucun secret, aucune étiquette par requête. Pour les traces et les métriques détaillées, utilisez le push OTLP. ## Push OTLP Définissez une seule variable pour activer la télémétrie : ```ini # gateway.env — export telemetry to your OTLP collector AIHUMMER_OTEL_ENDPOINT=http://otel-collector:4317 ``` Avec `AIHUMMER_OTEL_ENDPOINT` une fois configuré, la passerelle envoie la télémétrie à ce collecteur. De là, redirigez-la vers votre backend (Tempo, un magasin de métriques, des journaux) et dans Grafana. ## Gestion des paniques et des erreurs Les rapports d'erreurs **ne sont jamais envoyés à l'extérieur** : la passerelle n'embarque aucun client de traqueur d'erreurs externe ni aucun DSN externe — les données sur vos erreurs ne quittent jamais votre périmètre. La résistance aux paniques est néanmoins complète : - une panique dans un gestionnaire HTTP devient une réponse d'erreur ordinaire (un 500 portant une enveloppe `AIH-…`) — le processus ne meurt pas et continue de servir les autres requêtes ; - une panique dans une goroutine en arrière-plan est également récupérée et ne fait pas tomber la passerelle. Les deux cas atterrissent dans le journal structuré — consultez-les sur la page **Journaux** (ci-dessous) ou via `journalctl`. ## Journaux en direct dans l'interface d'administration L'interface d'administration **Journaux** la page est un journal en direct de la passerelle : de nouvelles lignes sont récupérées automatiquement toutes les quelques secondes, avec défilement automatique tant que vous êtes en bas. La barre d'outils a un **recherche de ligne** et un **filtre de niveau** (tous / erreurs / avertissements / info / debug). Plusieurs autres pages (Tableau de bord, Sessions, Canaux) se rafraîchissent également automatiquement, et de longues listes (audit, modifications, notifications, etc.) se chargent page par page avec un bouton « Afficher plus ». Les journaux complets de chaque service sont toujours présents dans systemd — `aihummer logs [unit]` ou `journalctl -u aihummer-gateway`. ## Tableaux de bord Grafana Des tableaux de bord Grafana prêts à l'emploi sont fournis avec la version. Importez-les dans votre instance Grafana pour obtenir les vues opérationnelles sans créer les panneaux à partir de zéro. ## Que regarder Voici les signaux qui vous indiquent que le système est sain et que les flux se déroulent : | Signal | Pourquoi c'est important | |---|---| | **Latence de tour** | Réactivité de bout en bout des tours d'agent | | **Taux d'erreur** | Échecs de tours / demandes — le premier signe de problème | | **Dispositions de livraison** | Si les réponses parviennent réellement aux chaînes | | **Livraisons en attente** | Arriéré de réponses non livrées ; une croissance soutenue signifie que la livraison est bloquée | Une augmentation soutenue de **livraisons en attente ou échouées à plusieurs reprises** est le signal d'alerte précoce le plus clair que la livraison est en train de s'accumuler — surveillez-le pendant les déploiements et les incidents. ## Points de terminaison du système Aux côtés de l'OTLP, la passerelle expose de petits points de terminaison HTTP utiles pour les sondes, les horloges et le diagnostic des clients : | Méthode | Point de terminaison | But | |---|---|---| | `GET` | `/metrics` | Métriques Prometheus (construction, exécution, pool de BD, disponibilité) | | `GET` | `/healthz` | Vivant + version | | `GET` | `/readyz` | Disponibilité (vérifie Postgres ; 503 si hors service) | | `GET` | `/v1/ping` | Vérification de l’accessibilité légère | | `GET` | `/v1/time` | Heure du serveur | | `POST` | `/v1/client-log` | Ingestion des événements de journal côté client | Les probes de santé et de disponibilité sont détaillées dans [systemd et contrôles de santé](/fr/v1.0/operations/systemd-health). ## Où aller ensuite - Sondes et la liste de contrôle pré-vol de production : [systemd et contrôles de santé](/fr/v1.0/operations/systemd-health). - Que regarder pendant une mise à niveau progressive : [Politique de mise à niveau](/fr/v1.0/operations/upgrade-policy).