Configuration de l'observabilité

Tale ship trois coutures d'observabilité : logs stdout depuis chaque conteneur, métriques au format Prometheus derrière un bearer token, et reporting d'erreurs Sentry optionnel. Les défauts sont assez bruyants pour repérer un crash et assez discrets pour tenir dans le journald d'un seul hôte ; les boutons de production ci-dessous ajoutent les chemins structurés que ta stack de monitoring existante peut scraper. Aucune des trois n'envoie quoi que ce soit hors-hôte sauf si tu le configures.

Cette page couvre les interrupteurs côté serveur. Le playbook d'alerte côté opérateur vit dans Opérations, et la recherche par symptôme dans Dépannage.

Logs

Chaque conteneur écrit des logs JSON structurés ou console vers stdout, capturés par le driver json-file par défaut de Docker avec une rotation de 10 Mo par fichier et 3 fichiers. La destination des logs est fonction de comment tu déploies :

• Hôte unique avec journald — journalctl -u docker porte le tout.
• Hôte unique sans journald — docker compose logs -f <service> pour le tailing en direct.
• Aggregator (Loki, Vector, Fluent Bit) — pointe le driver de logging Docker dessus via daemon.json.

Tale ne ship pas de log shipper. L'échange de driver est le point de connector supporté.

Métriques

Le proxy Caddy expose trois chemins de métriques derrière un seul bearer token :

Le travail de connaissances (recherche RAG, ingestion de documents, crawling web) tourne désormais dans le backend worker, donc ses timings empruntent la série /metrics/backend plutôt qu'un endpoint séparé. Mets METRICS_BEARER_TOKEN dans .env pour activer ces endpoints ; laisse-le non défini pour qu'ils retournent 401 à chaque requête. Le chemin /metrics/sla-rules est un fichier YAML de rules en lecture seule que tu charges dans Prometheus, pas une cible de scrape — les seuils qu'il porte sont documentés dans Opérations. Tout sauf les chemins listés retourne aussi 401, donc un scraper mal routé ne voit pas accidentellement les endpoints de santé internes de la plateforme.

/metrics/backend est servi par le backend applicatif, que chaque déploiement fait tourner ; BACKEND_UPSTREAM ne fait que surcharger l'upstream pour un déploiement scindé. Un chemin de métriques gated sans lane sur le déploiement répond 404 au lieu de servir en silence les chiffres d'un autre service sous le mauvais nom.

Une stanza de scrape Prometheus qui marche :

scrape_configs:
  - job_name: tale-platform
    scheme: https
    metrics_path: /metrics/platform
    authorization:
      credentials: <METRICS_BEARER_TOKEN>
    static_configs:
      - targets: ['tale.example.com']

Duplique la stanza par chemin, ou utilise un job unique avec relabel_configs si tu préfères.

Suivi d'erreurs avec Sentry

Sentry est opt-in via SENTRY_DSN. GlitchTip et Bugsink auto-hébergés marchent aussi, puisqu'ils parlent le même format de DSN. Un seul DSN couvre les deux côtés de la stack : l'app navigateur remonte les erreurs front-end, et les conteneurs backend-api / backend-worker remontent le côté serveur — requêtes plantées, jobs d'arrière-plan échoués et échecs au boot — tagués avec le rôle du processus (tale.role) et la version de release.

# .env
SENTRY_DSN=https://your-key@your-sentry-host/project-id
SENTRY_TRACES_SAMPLE_RATE=0.1

Le sample rate plafonne les traces de performance du navigateur et ne s'applique que là — le backend remonte des erreurs, jamais de traces. Laisse-le non défini pour le défaut 1.0 en développement et resserre-le (0.05–0.2) en production. Les stack frames sont envoyés sans rédaction des deux côtés, donc pointe le DSN sur une infra que tu contrôles si tes payloads d'erreur sont sensibles.

Ce qui ne ship pas encore

Les traces OpenTelemetry ne sont pas intégrées aux conteneurs. Les données sont joignables indirectement — les durées de requête backend et les timings de routes HTTP arrivent par les métriques Prometheus — mais il n'y a pas d'exportateur OTLP sur la boîte aujourd'hui. Si tu as besoin d'export de traces complet, fais tourner un OpenTelemetry Collector à côté de Tale et scrape les endpoints Prometheus depuis lui.

Où cela s'inscrit

Les trois coutures ci-dessus sont les points de contact avec le reste de ta stack de monitoring ; les seuils d'alerte et la checklist d'astreinte vivent dans Opérations. Si quelque chose brûle là, maintenant, et qu'il te faut l'index par symptôme, saute à Dépannage.