Prometheus Metrics FR - Kheopsian/Hydranos GitHub Wiki

🇬🇧 English · 🇫🇷 Français

Métriques Prometheus

S'applique à Hydranos 4.4.

Cette page est la référence de GET /metrics : chaque famille, ses labels, ce qui est servi pendant le démarrage d'Hydranos, une configuration de collecte et des règles d'alerte. Les points de santé, les journaux et les autres surfaces de supervision sont sur Supervision & journaux.

GET /metrics ne demande pas de clé API et renvoie Content-Type: text/plain; version=0.0.4. Chaque famille a ses lignes # HELP et # TYPE. Les chiffres viennent de compteurs qu'Hydranos tient déjà (le passage de débit une fois par seconde, les compteurs de l'annonceur, le dernier passage trackers de 30 s) : une collecte ne parcourt jamais le catalogue, donc son coût ne croît pas avec le nombre de torrents.

Les familles par moteur ont un échantillon par moteur local, moteurs supplémentaires compris (engine="vpn1"). Une famille sans aucun échantillon n'est pas affichée (par exemple hydra_seed_size_bytes avant le premier passage trackers, ou hydra_tracker_errors_last_hour quand aucune annonce n'a échoué dans la dernière heure).

Métriques

Métrique Type Labels Signification
hydra_up gauge — 1 tant que le processus répond.
hydra_build_info gauge version Toujours 1 ; la version en cours est le label.
hydra_uptime_seconds gauge — Secondes depuis le démarrage du processus, chargement du catalogue compris.
hydra_torrents gauge engine Torrents chargés dans le moteur.
hydra_torrents_by_state gauge engine, state Torrents par état : stopped, checking, downloading, seeding, error (error = les données manquent). Il n'y a pas d'état queued : un torrent que la file de téléchargement retient (active_downloads) ou un seed qu'elle met de côté (active_seeds) est compté sous stopped.
hydra_torrents_paused gauge engine Torrents dont le drapeau de pause est posé : arrêtés par l'opérateur, par une limite de partage, ou retenus par la file de téléchargement ; aussi comptés sous leur état ci-dessus.
hydra_upload_rate_bytes gauge engine Débit d'envoi, octets/s.
hydra_download_rate_bytes gauge engine Débit de réception, octets/s.
hydra_session_uploaded_bytes_total counter engine Octets envoyés depuis le démarrage du processus.
hydra_session_downloaded_bytes_total counter engine Octets reçus depuis le démarrage du processus.
hydra_lifetime_uploaded_bytes gauge engine Envoi à vie des torrents chargés maintenant ; baisse quand l'un d'eux est retiré.
hydra_lifetime_downloaded_bytes gauge engine Réception à vie des torrents chargés maintenant ; baisse quand l'un d'eux est retiré.
hydra_peers gauge engine Pairs connectés.
hydra_torrents_with_peers gauge engine Torrents avec au moins un pair.
hydra_torrents_uploading gauge engine Torrents en train d'envoyer.
hydra_seed_size_bytes gauge engine Taille des torrents en seed telle que les trackers la créditent (un cross-seed compte une fois par tracker). Absente jusqu'au premier passage trackers (toutes les 30 s).
hydra_announces_total counter engine, result (ok, failed) Annonces depuis le démarrage du processus.
hydra_tracker_announces_total counter engine, tracker, result (ok, failed) Annonces par hôte de tracker depuis le démarrage du processus.
hydra_tracker_errors_last_hour gauge engine, tracker, class Annonces échouées par hôte de tracker et par classe d'erreur sur les 60 dernières minutes. Absente quand il n'y en a aucune. class prend l'une de 9 valeurs : rate_limited, timeout, invalid_passkey, unknown_torrent, dns, connect, http_error, udp_proxied, other (voir Trackers & annonces).
hydra_announce_in_flight gauge engine Annonces en cours d'envoi.
hydra_announce_slots gauge engine Annonces autorisées en même temps (la concurrence de l'ordonnanceur).
hydra_announce_late gauge engine Torrents dont l'échéance d'annonce est dépassée de plus de 5 s.
hydra_announce_needed_per_second gauge engine Annonces par seconde qu'exigent les intervalles du catalogue.
hydra_rate_limit_bytes gauge engine, direction (up, down) Plafond de débit actif en octets/s, 0 = aucun ; engine="client" est le plafond de tout le client, au-dessus de tous les moteurs : ce n'est pas un moteur, excluez-le des sommes et panneaux par moteur ({engine!="client"}).
hydra_choking gauge engine 1 quand le choker est actif (choking = true).
hydra_unchoke_slots gauge engine Emplacements d'envoi par torrent que le choker accorde (max_uploads_per_torrent ; 0 ou absente = 4). Publiée même quand choking = false ; absente quand les emplacements sont illimités (valeur négative, le hoard du modèle).
hydra_listening gauge engine 1 quand l'écoute pair du moteur est liée.
hydra_held gauge engine 1 tant que start_paused retient les connexions et les annonces du moteur. Un moteur dont les annonces attendent un port redirigé (gluetun ou WireGuard géré) n'est pas compté ici : voir Ce que /metrics ne montre pas ci-dessous.
hydra_pieces_in_flight gauge engine Pièces en cours de récupération (réservées par un pair ou une webseed, pas encore vérifiées).
hydra_piece_buffer_bytes gauge engine Octets de blocs reçus détenus par les pièces en cours.
hydra_memory_allocated_bytes gauge — Octets que détient le processus, tels que jemalloc les compte. Linux/Unix uniquement.
hydra_memory_resident_bytes gauge — Octets résidents que jemalloc mappe ; bien au-dessus d'alloué, cela signifie des pages que SIGUSR2 peut rendre. Linux/Unix uniquement.

Les plafonds de débit et le choker sont décrits sur File d'attente, limites de partage et de débit.

Nombre de séries. Environ 31 séries par moteur local (dont cinq pour les états), 2 pour engine="client" et 5 pour tout le processus (hydra_up, hydra_build_info, hydra_uptime_seconds, les deux jauges mémoire). Par moteur et par hôte de tracker, ajoutez 2 pour hydra_tracker_announces_total et jusqu'à 9 pour hydra_tracker_errors_last_hour (seulement les classes qui ont échoué dans la dernière heure). Le nombre de torrents ne le change pas ; le nombre de moteurs et d'hôtes de trackers, si.

Ce que /metrics ne montre pas

Non exposé en 4.4 : rien sur la sortie réseau n'est dans /metrics : pas d'état du tunnel ni d'âge du handshake, pas de port redirigé, pas de verdict du kill switch (couvert, bloqué, non couvert), pas d'IP de sortie, pas d'indicateur de fuite DNS, et aucun signe que les annonces d'un moteur attendent un port redirigé (gluetun ou WireGuard géré). Un tel moteur n'est pas hydra_held, et ses torrents ne deviennent pas hydra_announce_late : chacun est remis en place environ une minute plus tard, encore et encore, si bien que son hydra_announces_total cesse simplement de croître. L'alerte HydranosEngineSilent ci-dessous le détecte. Pour le reste, interrogez les routes JSON, qui demandent la clé API (en-tête X-Api-Key) et donc un petit exporteur à vous (ou un exporteur JSON) :

Route Ce qu'il faut lire
GET /api/network/wireguard tunnels[], un par tunnel : engine, up, handshake_age_seconds, forwarded_port, degraded, dns_leak, last_error ; engines[].assignment
GET /api/network/egress le kill switch : armed, le verdict de chaque moteur, les moteurs bloqués
GET /api/network/mode engine_state[] : par moteur en marche, port_pending = true tant que ses annonces attendent un port redirigé
GET /api/port-forward par moteur : port détenu, reachable, inbound_peers, forward (qui redirige le port ; external_port à 0 tant qu'aucun n'est connu)

/health signale un moteur bloqué par le kill switch ou sans écoute (degraded), pas un moteur qui attend son port. Voir WireGuard géré et VPN & sortie réseau.

Aucun tableau de bord Grafana n'est livré avec la 4.4. Points de départ : sum by (engine) (hydra_upload_rate_bytes), sum by (engine, state) (hydra_torrents_by_state), hydra_announce_needed_per_second à côté de rate(hydra_announces_total[5m]), hydra_announce_late, sum by (tracker, class) (hydra_tracker_errors_last_hour), hydra_memory_resident_bytes.

Pendant le démarrage, /metrics répond déjà, avec un jeu réduit : hydra_up, hydra_uptime_seconds, hydra_starting (1), hydra_startup_restored{engine} (enregistrements de reprise traités jusqu'ici) et hydra_startup_records{engine} (enregistrements à traiter). Les trois derniers disparaissent une fois Hydranos prêt (il n'y a pas de hydra_starting 0), et les familles par moteur ci-dessus apparaissent.

Exemple (abrégé) :

# HELP hydra_up 1 while the process answers.
# TYPE hydra_up gauge
hydra_up 1
# HELP hydra_torrents Torrents loaded in the engine.
# TYPE hydra_torrents gauge
hydra_torrents{engine="race"} 42
hydra_torrents{engine="hoard"} 15000
hydra_torrents{engine="vpn1"} 800
# HELP hydra_announces_total Announces since the process started.
# TYPE hydra_announces_total counter
hydra_announces_total{engine="hoard",result="ok"} 120394
hydra_announces_total{engine="hoard",result="failed"} 87

Collecte

Configuration de collecte (prometheus.yml). Aucun identifiant n'est nécessaire :

scrape_configs:
  - job_name: hydranos
    metrics_path: /metrics
    scrape_interval: 30s
    static_configs:
      - targets: ["hydranos.example.org:8199"]

Si Prometheus tourne dans le même projet compose, utilisez plutôt le nom du service : targets: ["hydranos:8199"].

Plusieurs instances (par exemple une seconde dans gluetun, déclarée comme nœud) : collectez chacune comme sa propre cible. Hydranos n'ajoute aucun label d'instance ni de nœud à ses séries ; Prometheus ajoute instance (l'adresse de la cible), et vous pouvez ajouter votre propre label par cible. Chaque instance a besoin de son propre port hôte : publiez le 8199 de la seconde sur un autre port hôte ("18199:8199", sur le conteneur gluetun quand elle partage le réseau de gluetun), ou changez son api_port (Config : démon, auth & global).

    static_configs:
      - targets: ["hydranos.example.org:8199"]
        labels: { hydranos: "home" }
      - targets: ["hydranos.example.org:18199"]
        labels: { hydranos: "gluetun" }

Comme la page est publique, quiconque peut joindre le port 8199 peut la lire — y compris, dans le label tracker, les noms d'hôte de tous les trackers que vous utilisez, et vos volumes de transfert. Gardez le port 8199 hors d'internet ou derrière un reverse proxy qui restreint /metrics ; voir Sécurité & accès.

Alertes

groups:
  - name: hydranos
    rules:
      - alert: HydranosDown
        expr: up{job="hydranos"} == 0
        for: 5m
      - alert: HydranosRestartLoop
        expr: resets(hydra_uptime_seconds[1h]) >= 3
      - alert: HydranosTorrentsDropped
        expr: sum(hydra_torrents) < 0.9 * sum(hydra_torrents offset 1h)
        for: 15m
      - alert: HydranosEngineNotListening
        expr: hydra_listening == 0
        for: 5m
      - alert: HydranosEngineHeld
        expr: hydra_held == 1
        for: 30m
      - alert: HydranosAnnouncesFailing
        expr: |
          sum by (engine) (increase(hydra_announces_total{result="failed"}[15m]))
            / sum by (engine) (increase(hydra_announces_total[15m])) > 0.2
        for: 15m
      - alert: HydranosAnnouncesLate
        expr: hydra_announce_late > 1000
        for: 15m
      - alert: HydranosEngineSilent
        expr: sum by (engine) (increase(hydra_announces_total[30m])) == 0 and on (engine) hydra_torrents > 0
        for: 15m

hydra_uptime_seconds ne fait que croître pendant la vie d'un processus et repart de 0, donc resets() (documentée pour les compteurs) compte ici les redémarrages : un seul redémarrage ou une seule mise à jour planifiés ne déclenchent pas HydranosRestartLoop ; trois en une heure, si. HydranosTorrentsDropped repère un catalogue qui a rétréci de plus de 10 % (une mauvaise restauration, un drain ou un workflow qui a trop retiré). HydranosEngineNotListening se déclenche aussi pour un moteur que vous tenez volontairement hors du réseau (HYDRANOS_ENGINE_NET=0) ; excluez-le avec {engine!="…"}. Les seuils de retard et d'échec sont des exemples : réglez-les sur ce qui est normal pour votre bibliothèque. hydra_tracker_errors_last_hour vous dit quel tracker et quelle classe d'erreur sont derrière une alerte d'échec. HydranosEngineSilent se déclenche pour un moteur qui n'a rien annoncé pendant 30 minutes alors qu'il détient des torrents : annonces en attente d'un port redirigé, moteur retenu ou bloqué par le kill switch, ou moteur dont tous les torrents sont arrêtés.

Voir aussi