Supervision

Heron ne fait pas tourner Prometheus ni Grafana lui-même. Il fournit des métriques, un tableau de bord et des règles d’alerte à utiliser avec votre propre Grafana, auto-hébergé ou Grafana Cloud.

Démarrage rapide avec Grafana Cloud

Dans votre stack Grafana Cloud, ouvrez les détails de la source de données Prometheus. Notez le point d’envoi remote write et l’ID d’instance.
Créez un jeton d’accès avec la portée metrics:write.

Dans .env :

HERON_STATION_NAME=radio1
HERON_METRICS_REMOTE_WRITE_URL=https://prometheus-prod-XX-prod-REGION.grafana.net/api/prom/push
HERON_METRICS_REMOTE_WRITE_USERNAME=123456
HERON_METRICS_REMOTE_WRITE_PASSWORD=glc_…

docker compose up -d. Chaque service journalise pushing metrics with remote write.
Dans Grafana, importez monitoring/grafana/heron-dashboard.json depuis le dépôt et choisissez votre source Prometheus.
Chargez les règles d’alerte et configurez un point de contact.

Envoyer les métriques

Remote write (envoi). Avec HERON_METRICS_REMOTE_WRITE_URL renseigné, chaque service envoie ses métriques toutes les 15 s. La station ne fait que des requêtes HTTPS sortantes : cela fonctionne derrière un NAT. Prometheus 2.33+ (avec --web.enable-remote-write-receiver), Grafana Mimir, VictoriaMetrics et Thanos Receive l’acceptent. Un envoi raté n’est jamais réessayé et n’arrête jamais un service.

Collecte (scraping). Laissez l’URL vide et collectez /metrics sur chaque service :

Service	Port
`heron-engine`	8081 (toutes les 5 s)
`heron-api`	8080
`heron-analyzer`	8082
`heron-librarian`	8083

Ces ports n’ont pas d’authentification. Rattachez votre Prometheus au réseau Docker de Heron (heron_default), ou publiez-les seulement sur 127.0.0.1 ou un réseau privé, jamais sur Internet.

Chaque série porte job (le service) et station (HERON_STATION_NAME).

Le tableau de bord

monitoring/grafana/heron-dashboard.json (Grafana 12 ou suivant) montre :

À l’antenne : blanc d’antenne, silence, sorties connectées, pistes en file, niveau général, pistes de secours et sauts pour silence ;
Santé du moteur audio : sous-alimentations, audio perdu, reconnexions, retard et dérive de l’horloge ;
Horloge du serveur, plan de contrôle, bibliothèque et versions en service.

Une station en bonne santé ne montre aucun blanc d’antenne, toutes ses sorties connectées, deux pistes ou plus en file, une dérive d’horloge plate, et zéro sous-alimentation ou audio perdu.

Alertes

monitoring/prometheus/alerts.yml est un fichier de règles Prometheus standard. Chargez-le avec mimirtool (Grafana Cloud, Mimir) ou listez-le dans rule_files (Prometheus).

Les alertes critiques signifient que les auditeurs entendent le problème, ou vont l’entendre : moteur arrêté, blanc d’antenne, silence à l’antenne, sortie déconnectée depuis 2 min, audio perdu. Les avertissements signifient que l’antenne tient mais que quelque chose mérite un coup d’œil : pistes de secours jouées, sauts pour silence, sous-alimentations, sorties instables, horloge du serveur désynchronisée, un service ou le lien de l’API vers le moteur coupé, analyses ou parcours en échec, nombreux échecs de connexion.

Contrôles de santé

Chaque service répond à GET /healthz :

{"service": "heron-engine", "version": "0.1.0", "status": "ok"}

Il répond 503 quand le service est en mauvaise santé, et liste des warnings pour les problèmes qui demandent attention, comme une horloge désynchronisée ou plus rien à jouer. Les contrôles de santé de Docker l’utilisent.

De l’extérieur, surveillez aussi ce que reçoivent les auditeurs : une vérification HTTP de l’URL du flux (Uptime Kuma, UptimeRobot, Grafana Synthetic Monitoring) détecte les problèmes de DNS, de TLS, de réseau et de serveur de flux.

Journaux

Les conteneurs journalisent un objet JSON par ligne. Réglez le niveau avec RUST_LOG dans .env, et suivez un service avec :

docker compose logs -f heron-engine

Sentry

Renseignez HERON_SENTRY_DSN pour envoyer les erreurs des services à Sentry (sentry.io ou auto-hébergé), et HERON_WEB_SENTRY_DSN, dans un projet à part, pour l’interface web.