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 d'intégration 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 Convex, donc ses timings empruntent la série /metrics/convex 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.

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. Les conteneurs plateforme et convex lisent tous les deux le DSN et taguent les événements avec le nom du conteneur.

# .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 ; 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, 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 d'action Convex 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.