Configurer la supervision

Commence par les journaux des conteneurs et l’état des services. Ajoute les métriques Prometheus pour suivre les tendances et déclencher des alertes, puis un service de suivi des erreurs si tu veux consulter leur historique. Tale n’envoie ces données à un service de supervision externe que si tu en configures un.

Consulter les journaux de l’application

Les conteneurs écrivent sur stdout et stderr. La configuration Compose fournie utilise le pilote Docker json-file, avec une rotation à 10 Mo par fichier et trois fichiers par conteneur. Utilise les noms de services de ton fichier Compose :

docker compose logs --tail=100 backend-api backend-worker
docker compose logs -f backend-api

Appuie sur Ctrl-C pour arrêter le suivi ; les conteneurs continuent de fonctionner. Consulte backend-api pour les requêtes, la connexion et les réponses du chat interactif ; utilise backend-worker pour les tâches de fond, les appels d’agent mis en file et l’importation des documents. docker compose ps permet de repérer un conteneur qui redémarre en boucle.

journalctl -u docker affiche le journal du démon Docker. Avec le pilote par défaut json-file, il ne remplace pas les journaux des conteneurs. Pour utiliser journald ou centraliser les journaux, configure séparément le pilote Docker et leur collecte. Tale ne fournit pas d’agent de collecte. Un changement de pilote exige de recréer les conteneurs concernés.

Activer les métriques protégées

Définis un METRICS_BEARER_TOKEN robuste dans l’environnement du déploiement. Applique la modification avec ta procédure habituelle afin de recréer les services concernés. Un simple redémarrage de conteneur ne recharge pas les variables d’environnement de Compose. Enregistre le même jeton dans le gestionnaire de secrets de ton système de supervision.

Le proxy exige Authorization: Bearer <token> pour ces routes. Sans jeton configuré, elles renvoient 401.

Le backend traite les recherches de connaissances et les tâches d’importation. Ses métriques HTTP et de file d’attente aident à repérer les erreurs et les retards ; elles ne mesurent pas séparément la durée de la recherche ou de la génération. BACKEND_UPSTREAM désigne la cible backend d’un déploiement séparé. Cette variable ne crée pas de service de métriques propre aux connaissances.

Crée une tâche de collecte par route. Dans cet exemple, /run/secrets/tale_metrics_token est un fichier du conteneur Prometheus qui contient uniquement le jeton. Crée-le avec ton gestionnaire de secrets et autorise Prometheus à le lire.

scrape_configs:
  - job_name: tale-platform
    scheme: https
    metrics_path: /metrics/platform
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']
  - job_name: tale-backend
    scheme: https
    metrics_path: /metrics/backend
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']

Ne collecte pas /metrics/sla-rules comme des métriques. Les règles générées utilisent des séries de latence qui nécessitent une instrumentation supplémentaire. Charger le fichier ne suffit pas à mesurer le respect des objectifs de réponse. Examine les règles avant de les charger dans Prometheus. La page Prometheus et Grafana détaille l’installation complète.

Choisir la destination des erreurs

SENTRY_DSN active le suivi facultatif des erreurs. Il peut désigner Sentry ou un service compatible comme GlitchTip ou Bugsink. Le navigateur, le backend et la sandbox utilisent ce DSN et le libellé SENTRY_ENVIRONMENT ; les événements serveur indiquent le rôle du processus et la version déployée.

SENTRY_DSN=https://your-key@your-sentry-host/project-id
SENTRY_ENVIRONMENT=example-pr
SENTRY_TRACES_SAMPLE_RATE=0.1

Les déploiements gérés utilisent leur name existant comme libellé par défaut. Pour choisir un autre libellé, déclare "environment": { "SENTRY_ENVIRONMENT": { "env": "TALE_REPORTING_ENVIRONMENT" } } dans la spécification du déploiement et définis cette variable à destination. La valeur commence par une lettre minuscule ou un chiffre et contient de 1 à 64 lettres minuscules, chiffres ou traits d’union. L’identité du déploiement, son état et ses identifiants enregistrés conservent leurs chemins existants.

Les erreurs de sandbox comprennent les échecs HTTP et des tâches de fond. Les annulations attendues du client et les flux SSE fermés après annulation sont exclus. La sandbox envoie uniquement des erreurs ; les paramètres de traces du navigateur et du backend n’activent pas de traces dans la sandbox. Elle utilise le filtre de confidentialité du backend décrit ci-dessous.

SENTRY_TRACES_SAMPLE_RATE concerne les traces de performance du navigateur ; leur taux par défaut est de 1.0 en développement. Les traces du backend sont désactivées par défaut. Pour les activer, règle BACKEND_SENTRY_TRACES_SAMPLE_RATE entre 0 et 1 (par exemple, 0.05 échantillonne 5 % des opérations) et utilise une destination qui accepte les transactions Sentry. Recrée les services API et worker du backend après la modification. Choisis des taux adaptés à ton budget de supervision ; le taux backend 0 désactive les spans tout en conservant le suivi des erreurs.

Les spans du backend mesurent le traitement des requêtes HTTP et l’exécution des tâches d’arrière-plan. Une tâche comprend des spans enfants pour le contrôle du drainage, son traitement ou son transfert. Les contrôles d’état et les collectes de métriques sont exclus ; les spans HTTP ne mesurent pas la durée de transmission du corps d’une réponse en continu. Leurs noms utilisent des classes de routes et les noms de files enregistrées. Les spans excluent le contenu des requêtes et des tâches, le texte SQL, les identifiants, les URL, le contexte utilisateur et les fils d’activité. Les requêtes sortantes ne portent aucun en-tête de trace. Le travail des agents ajoute des spans enfants pour l’acquisition, la préparation du gateway, le staging, l’exécution, la persistance et la récupération des fichiers. Leurs noms sont fixes et ils ne contiennent ni prompts, ni chemins de fichiers, ni identifiants secrets.

Les événements du backend n’incluent jamais les cookies ni le corps des requêtes. Les en-têtes d’autorisation, de cookie, de clé d’API, de jeton, de secret et de session, les jetons de webhook et de partage dans les URL ainsi que les valeurs d’identification des paramètres de requête, comme les codes OAuth, sont remplacés par [Filtered] avant l’envoi. Les cadres de pile et les messages d’erreur sont envoyés tels quels ; choisis la destination selon tes exigences de traitement des données.

Un redémarrage de la base de données n’est pas signalé comme une erreur : une mise à niveau gérée recrée la base à chaque version. Tant qu’elle est injoignable, les requêtes répondent 503 DATABASE_UNAVAILABLE avec Retry-After, les tâches d’arrière-plan échouent puis sont relancées selon la politique de leur file, et les flux de mise à jour en direct ouverts patientent puis reprennent. Chacun écrit un avertissement dans le journal à la place. La file des tâches n’en écrit qu’un pour toute la panne, et non un à chaque interrogation échouée. Si la base reste injoignable plus d’une minute environ, un processus API ayant des flux ouverts envoie un seul événement de niveau « warning » pour cette panne. Un processus backend qui démarre pendant que la base est injoignable, ou qui la perd avant le démarrage de sa file des tâches, l’attend jusqu’à une minute environ au lieu de s’arrêter, et écrit un avertissement dans le journal à chaque nouvelle tentative. Si la base reste injoignable au-delà, le démarrage échoue et est signalé comme une erreur. Un hôte ou un port erroné dans DATABASE_URL ne fait donc échouer le démarrage qu’au bout d’une minute environ.

Le backend ne signale pas non plus une requête abandonnée par son client, par exemple quand tu fermes un onglet ou annules un téléversement pendant que son corps arrive encore. La requête reçoit le statut 499, compte parmi les erreurs client dans les métriques de requêtes et laisse une seule ligne de débogage dans le journal. Toute autre erreur survenue dans une requête dont le client s’est déconnecté reste signalée. Une requête de l’application dont le corps JSON est vide ou tronqué reçoit 400 INVALID_JSON et n’est pas signalée.

Le navigateur ne signale pas les erreurs qui ne révèlent aucun défaut de Tale :

• les erreurs provenant d’une extension du navigateur
• les requêtes que la page annule elle-même, par exemple quand tu la quittes avant la fin de son chargement
• les requêtes que le backend refuse avec un statut inférieur à 500, par exemple faute d’autorisation ou parce qu’un nom est déjà pris
• les requêtes restées sans aucune réponse, par exemple quand l’appareil est hors ligne
• les requêtes qui échouent pendant que la plateforme ou sa base de données redémarre : UPSTREAM_UNAVAILABLE du proxy pendant un déploiement ou un redémarrage, et 503 DATABASE_UNAVAILABLE de la plateforme

Les autres erreurs serveur, de statut 500 ou plus, restent signalées.

Statistiques agrégées avec Umami

La collecte est désactivée par défaut. Tu l’actives séparément pour chaque déploiement avec UMAMI_URL, UMAMI_WEBSITE_ID et UMAMI_PROXY_TOKEN, décrits dans la référence des variables d’environnement. Utilise un identifiant de site distinct par déploiement. Recrée le service de production concerné avec les nouvelles variables ; il n’est pas nécessaire de reconstruire l’image. Pour arrêter la collecte, vide l’identifiant de site et applique la modification de la même façon. Le serveur de développement Vite n’injecte pas cette configuration.

Le navigateur charge le script Umami depuis sa propre origine, sous /_a/script.js, et envoie les événements sélectionnés à /_a/api/send. Si un chemin de base est configuré, il précède ces URL. Seuls l’identifiant de site et le chemin du proxy figurent dans la configuration du navigateur ; l’origine de collecte et le jeton Bearer restent sur le serveur.

UMAMI_URL doit désigner une passerelle qui authentifie GET /_collect/script.js et POST /_collect/api/send avec ce jeton Bearer. L’URL d’un tableau de bord Umami standard ne suffit pas à fournir cette interface. Caddy doit remplacer X-Analytics-Client-IP par une adresse client issue d’une source de confiance. Garde les ports applicatifs privés et configure les plages d’adresses des proxys de confiance si un autre proxy se trouve en amont. Le serveur transmet l’IP validée, le User-Agent du navigateur et les en-têtes Umami nécessaires ; il retire les cookies, les identifiants de connexion et les en-têtes de provenance du navigateur.

Les rapports contiennent les chemins publics connus ou les modèles de routes privées de la plateforme, les origines de provenance, la langue du navigateur, la taille de l’écran, le navigateur, le système, l’appareil et la localisation approximative. La collecte déduit les visites et la localisation de l’IP sans conserver l’adresse brute. Des paramètres génériques remplacent les identifiants privés d’organisation et de ressource. Les titres de page, paramètres de recherche, fragments, champs de formulaire et contenus produit sont exclus. Le site marketing compte aussi les demandes de contact et de démo abouties, sans leur contenu. Il n’y a ni identité entre sites, ni capture automatique des clics, ni enregistrement des sessions. Do Not Track et Global Privacy Control désactivent la collecte.

Après le déploiement, vérifie le comportement avec un navigateur qui autorise la collecte :

1. Ouvre une page connue, passe à une autre et vérifie les deux pages vues dans le site Umami du déploiement.
2. Inspecte le corps de la requête. Les routes privées contiennent des paramètres génériques, sans paramètres de recherche, titres ni données de formulaire.
3. Active Do Not Track ou Global Privacy Control et vérifie que la collecte s’arrête.
4. Bloque la collecte ou teste son indisponibilité. La navigation normale doit continuer à fonctionner.

Connaître les limites

Tale n’exporte actuellement pas de traces OpenTelemetry par OTLP. Un OpenTelemetry Collector peut collecter les métriques Prometheus, mais cette collecte ne produit pas de traces distribuées. L’export de traces de bout en bout exige aussi une instrumentation de l’application.

Pour les seuils d’alerte et les procédures d’intervention, consulte Exploitation. Si un service échoue, utilise les tableaux de symptômes du Dépannage.