Monitoring

Tableau de bord web

Démarrer le tableau de bord

/bench monitor web start

Par défaut, le tableau de bord n'écoute que sur cette machine : http://localhost:8080 (voir Configuration pour l'atteindre depuis ailleurs). Il affiche, avec des graphiques en direct :

• TPS (Ticks Par Seconde) - l'objectif est 20.0
• MSPT (Millisecondes Par Tick) - plus bas, c'est mieux
• RAM utilisée (part du tas maximal)
• Utilisation CPU
• Entités, avec une répartition (hostiles, passives, neutres, items, projectiles, véhicules, drops, autres)
• Chunks chargés

L'en-tête affiche aussi le logiciel serveur et le nombre de joueurs connectés (sans graphique).

La page est disponible en anglais et en français (sélecteur en haut de page, ou langue du navigateur).

Arrêter le tableau de bord

/bench monitor web stop

/bench monitor web sans argument le bascule. /bench monitor web start et /bench monitor web status affichent les adresses locales du tableau de bord et de /api/metrics, avec le schéma et le port sur lesquels le serveur écoute réellement : http://localhost:8080 par défaut, https://localhost:8443 quand HTTPS est activé. status affiche aussi les réglages de sécurité.

Configuration

monitor:
  web-port: 8080              # Port du serveur web
  bind-address: "127.0.0.1"   # Interface réseau (127.0.0.1 = cette machine seulement)
  dashboard:
    enabled: true             # false = uniquement /api/metrics, sans page HTML

Pour atteindre le tableau de bord depuis d'autres machines, réglez bind-address sur "0.0.0.0" (toutes les interfaces) ou sur une adresse du serveur. Le tableau de bord refuse alors de démarrer tant qu'aucun mot de passe n'est posé (voir Authentification) : sans mot de passe, il publierait votre TPS, vos joueurs et la version du serveur à quiconque trouve le port. Derrière un proxy inverse qui porte sa propre authentification, gardez 127.0.0.1 et laissez le proxy y accéder en local. Un config.yml existant encore réglé sur 0.0.0.0 sans mot de passe reçoit le même refus, avec la marche à suivre dans le message.

/bench monitor web dashboard off passe en mode API seule. Après avoir modifié ces réglages, redémarrez le serveur web (/bench monitor web stop, puis start).

Démarrage automatique

Pour démarrer automatiquement le tableau de bord au lancement du serveur :

monitor:
  auto-start:
    web-server: true

Section Profils (expérimentale)

Sous les graphiques, une section Profils en lecture seule liste les profils enregistrés par le profileur (/bench profile), du plus récent au plus ancien, et montre le résumé de celui sur lequel vous cliquez : qui tourne sur le thread de tick, les méthodes les plus coûteuses, les avertissements, et s'il a été envoyé sur voxelbench.com ou partagé par lien public (avec les liens). Tout le reste — capturer, partager, envoyer, supprimer — se fait en jeu.

La page lit GET /api/profiles (la liste) et GET /api/profiles/<id> (un profil). Ces routes demandent la même connexion ou clé d'API que /api/metrics, obéissent aux deux modes de whitelist (dashboard et api), n'acceptent que GET (et HEAD) et ne renvoient jamais le jeton qui supprime un lien public. Elles n'existent que lorsque le tableau de bord HTML est activé.

HTTPS (SSL/TLS)

Pour un accès sécurisé, vous pouvez activer HTTPS.

Générer un certificat

/bench monitor https generate [jours]

Cela crée un certificat auto-signé valable 365 jours par défaut, dans plugins/VoxelBench/certificates/keystore.jks, et enregistre son mot de passe dans config.yml. La commande utilise l'outil keytool du JDK, qui doit être disponible sur le serveur.

Activer HTTPS

/bench monitor https on

ou dans config.yml :

monitor:
  https:
    enabled: true
    port: 8443
    keystore-path: "certificates/keystore.jks"
    keystore-password: ""     # Rempli par la commande generate
    key-alias: "voxelbench"

Quand HTTPS est activé, le tableau de bord est servi sur le port HTTPS (monitor.https.port) au lieu du port HTTP, et /bench monitor web start et status affichent https://localhost:<port>. Redémarrez le serveur web pour appliquer.

Utiliser votre propre certificat

Si vous avez votre propre certificat SSL, importez-le dans un keystore Java :

keytool -importkeystore -srckeystore votre-cert.p12 -srcstoretype PKCS12 \
    -destkeystore plugins/VoxelBench/certificates/keystore.jks -deststoretype JKS

Réglez ensuite le chemin et l'alias du keystore dans config.yml, et le mot de passe avec /bench monitor https password <mot de passe>.

Authentification

Protégez votre tableau de bord avec un nom d'utilisateur et un mot de passe.

Configurer l'authentification

1. Définissez un mot de passe depuis la console du serveur (une commande tapée en jeu est écrite dans latest.log avec le mot de passe en clair, le plugin la refuse donc en jeu). Il doit faire au moins 12 caractères, et active aussi l'authentification :

bench monitor auth password VotreMotDePasseSecurise

2. Changez éventuellement le nom d'utilisateur (admin par défaut) :

/bench monitor auth username monnom

Le mot de passe est stocké dans config.yml sous forme de hash PBKDF2 (210 000 itérations), jamais en clair ; un mot de passe posé avec une version antérieure fonctionne toujours et passe en PBKDF2 à la connexion suivante. Après 5 échecs de connexion en une minute depuis la même adresse, la page de connexion répond « trop d'essais » pendant cette minute, et elle suit la whitelist IP comme le tableau de bord. En HTTPS, le cookie de session porte l'attribut Secure. Les sessions durent session-timeout minutes :

monitor:
  auth:
    enabled: true
    username: "admin"
    session-timeout: 60    # Durée de session en minutes

/bench monitor auth affiche l'état actuel de l'authentification. Redémarrez le serveur web après un changement.

Clé API

Pour l'accès programmatique (curl, Postman, scripts) quand l'authentification est activée :

/bench monitor auth key pull

Cela génère une clé enregistrée sous monitor.auth.api-key. Envoyez-la dans l'un de ces en-têtes pour lire /api/metrics sans session web :

curl -H "Authorization: Bearer VOTRE_CLE_API" http://votre-serveur:8080/api/metrics
curl -H "X-API-Key: VOTRE_CLE_API" http://votre-serveur:8080/api/metrics

Whitelist IP

Restreindre l'accès par adresse IP :

monitor:
  whitelist:
    enabled: true
    mode: "all"            # all, dashboard ou api
    allowed-ips:
      - "127.0.0.1"
      - "::1"
      - "192.168.1.100"
    denied-message: "Access denied: Your IP is not whitelisted"

Modes de whitelist

Le JSON des profils (/api/profiles) est du contenu du tableau de bord servi en JSON : il obéit à la whitelist dans les trois modes.

Gérer la whitelist en jeu

/bench monitor whitelist on
/bench monitor whitelist add 192.168.1.100
/bench monitor whitelist remove 192.168.1.100
/bench monitor whitelist list
/bench monitor whitelist mode dashboard

Derrière un reverse proxy

Si le tableau de bord n'est joignable qu'à travers un reverse proxy de confiance (nginx, Caddy, Cloudflare Tunnel...), mettez monitor.behind-proxy: true pour que l'IP du client soit lue dans l'en-tête X-Forwarded-For. Laissez false pour un tableau de bord exposé directement : sinon n'importe quel client pourrait falsifier cet en-tête et contourner la whitelist.

Boss Bars

Afficher des métriques en direct sous forme de boss bars en haut de l'écran :

/bench monitor bars              # Basculer TPS + MSPT
/bench monitor bars all          # Afficher toutes les métriques
/bench monitor bars cpu          # Basculer une métrique
/bench monitor bars off          # Masquer toutes les boss bars

Métriques : tps, mspt, ram, ramfree, cpu, entities, chunks, players.

Au démarrage des boss bars, elles s'affichent pour tous les joueurs connectés, puis pour chaque joueur qui se connecte tant qu'elles sont actives. Une métrique ajoutée alors que des barres sont déjà affichées (bars all, bars <métrique>) n'apparaît que pour le joueur qui a tapé la commande et pour les joueurs qui se connectent ensuite. Démarrées par auto-start (ci-dessous), les barres s'affichent pour les opérateurs et les joueurs disposant de voxelbench.monitor connectés à ce moment-là, puis pour chaque joueur qui se connecte.

Démarrage automatique des boss bars

monitor:
  auto-start:
    boss-bars: true

Mode Push

Envoyer les métriques vers un service externe (Grafana, tableau de bord personnalisé, etc.).

Configuration

monitor:
  push:
    url: "https://mon-serveur.com/api/metrics"
    api-key: "votre-cle-api"
    interval-seconds: 1
    allow-insecure: false    # Accepter les certificats SSL non vérifiés

/bench monitor auth key push génère une clé aléatoire et l'enregistre sous monitor.push.api-key.

Démarrer/arrêter le mode push

/bench monitor push start
/bench monitor push stop
/bench monitor push test      # Envoyer une requête pour vérifier les réglages
/bench monitor push status    # Compteurs de succès et d'erreurs

La valeur monitor.push.enabled n'est qu'affichée dans l'interface : le mode push démarre avec la commande ci-dessus ou avec le démarrage automatique.

Démarrage automatique du mode push

monitor:
  auto-start:
    push-service: true

Format des données push

Chaque envoi est une requête POST dont le corps JSON est le même document que /api/metrics. Quand une clé API est configurée, elle est envoyée dans les en-têtes Authorization: Bearer <cle-api> et X-VoxelBench-ApiKey. L'en-tête X-Server-Name indique le nom du logiciel serveur.

Tableau de bord voxelbench.com

Le monitoring distant envoie des relevés de métriques et les événements détectés à la page Monitoring de votre tableau de bord sur voxelbench.com. Contrairement au tableau de bord web ci-dessus, rien n'écoute sur votre serveur : le plugin envoie, le site conserve et trace. Il nécessite un serveur lié et une offre qui inclut le monitoring.

/bench monitor remote on       # L'activer et vérifier la connexion tout de suite
/bench monitor remote status   # Liaison, état du service, dernier contact, dernier envoi, ce que le site a gardé
/bench monitor remote off      # Arrêter l'envoi

on écrit remote-monitoring.enabled: true, démarre le service, indique ce qui sera envoyé (les métriques, et les sources d'événements actives), interroge aussitôt le site, puis indique en jeu ce qu'il reste à faire : rien (les données arrivent), activer le monitoring de ce serveur sur le site, vérifier l'offre, désactiver le monitoring d'un autre serveur quand la limite de serveurs surveillés de l'offre est atteinte, ou relier de nouveau le serveur. off prévient le site que le monitoring a été coupé volontairement (monitoring_paused) avant de s'arrêter : le site ne prend pas le silence pour une panne.

Ce que contient un relevé

Chaque relevé décrit tout l'intervalle depuis le précédent, pas un instant :

Le monitoring distant mesure avec ses propres fenêtres, alimentées par la source de ticks unique du plugin (voir Métriques de tick, GC et CPU) : un benchmark lancé sur le serveur ne les remet pas à zéro. Le battement, toutes les 30 secondes, indique aussi depuis quand le thread principal (la région globale sous Folia) n'a plus tiqué : un serveur figé ne paraît plus en ligne.

Folia : chaque région. Sous Folia, chaque région tique sur son propre thread : un seul TPS pour tout le serveur ne dit pas grand-chose. Chaque relevé mesure toutes les régions que Folia fait tiquer — y compris celles sans joueur, fermes et chargeurs de chunks — et les liste, les pires d'abord, dans regions : monde, bloc central (les coordonnées qu'affiche /tps de Folia), chunks, joueurs, entités, TPS, durée moyenne, 95e centile et pire tick. tps, mspt, mspt_p95, mspt_max, ticks_over_50ms et lag_seconds portent la pire région pour chaque valeur, tps_avg et mspt_avg la moyenne sur toutes les régions. La liste compte 64 régions au plus (remote-monitoring.folia-regions.max-detailed) ; les autres sont seulement comptées. Une région fusionnée dans une autre, scindée ou déchargée est retirée, pas signalée comme figée. Sur un dérivé de Folia dont les régions sont illisibles, le plugin mesure à la place les zones autour des joueurs (TPS seulement) et le signale une fois dans la console.

Pause d'un serveur vide. Depuis Minecraft 1.21.2, un serveur resté sans joueur pendant pause-when-empty-seconds (server.properties, 60 secondes par défaut) cesse de tiquer. Le battement et les relevés portent alors paused: true, pour que voxelbench.com ne prenne pas la pause pour un gel. Jamais tant qu'un joueur est connecté.

/bench monitor remote status affiche combien de relevés voxelbench.com a gardés et refusés depuis le démarrage du service, chaque motif de refus avec son nombre et le dernier, les relevés renvoyés après un délai (gardés une fois) et, à partir de 5 secondes, l'écart entre l'horloge du serveur et celle du site (que le site corrige).

Le monitoring doit aussi être activé pour le serveur sur voxelbench.com. L'ordre n'a pas d'importance : tant que le site refuse les données, le plugin se met en pause et revérifie tout seul, chaque minute (toutes les 10 minutes quand l'offre n'inclut pas le monitoring, ou quand ce serveur dépasse la limite de serveurs surveillés de l'offre), puis commence à envoyer dès que le site accepte. Si le site ne reconnaît plus la liaison, le service s'arrête jusqu'au prochain /bench link ; remote-monitoring.enabled reste tel que vous l'avez réglé.

Au-delà de la limite de serveurs surveillés de l'offre. Quand votre offre inclut le monitoring mais que plus de serveurs s'en servent qu'elle n'en permet (après un passage à une offre inférieure, par exemple), le site n'accepte que les derniers serveurs liés. Les autres se mettent en pause : /bench monitor remote on et la console indiquent que la limite est atteinte et que ce serveur n'est pas parmi les derniers liés, /bench monitor remote status affiche « En pause - au-delà de la limite de serveurs surveillés de votre offre », et le plugin revérifie toutes les 10 minutes. Pour reprendre, désactivez le monitoring d'un autre serveur sur la page Monitoring de votre tableau de bord, ou changez d'offre.

Si votre offre n'autorise pas une catégorie d'événements (par exemple les événements moderation de LiteBans), cette catégorie cesse d'envoyer jusqu'au prochain /bench reload, et /bench monitor remote status l'indique. Les métriques et les autres catégories continuent.

Les réglages (intervalles, événements) sont dans la section remote-monitoring ; /bench reload les applique.

Métriques de tick, GC et CPU

VoxelBench mesure chaque tick du serveur dès le démarrage, quoi qu'il soit activé par ailleurs, sans dépendre de spark. Une seule source de ticks et un seul écouteur du ramasse-miettes servent tout le plugin : la section performance de /api/metrics, les placeholders de durée de tick et le monitoring distant lisent les mêmes mesures. Chaque tick est donc mesuré une fois, et toutes les vues concordent. Il n'y a aucun réglage, et les scores de benchmark se mesurent exactement comme avant.

Rien de cette section n'est envoyé à voxelbench.com : les relevés distants ne portent que les champs de Ce que contient un relevé. Une valeur qui ne peut pas être mesurée sur votre serveur est omise, jamais affichée à 0.

Origine des durées de tick

Un dérivé de Paper qui embarque l'événement de fin de tick sans jamais le déclencher passe à main_thread_cpu environ cinq secondes après le démarrage.

Fenêtres

/api/metrics présente des fenêtres glissantes de 10 secondes, 1 minute, 5 minutes et 15 minutes, recalculées au plus une fois par seconde. Elles se chevauchent. Juste après un redémarrage, une fenêtre ne couvre que le temps écoulé depuis le démarrage (covered_s). L'historique garde environ 20 000 ticks (17 minutes à 20 TPS) : sous Folia, avec plusieurs régions actives, les fenêtres les plus longues peuvent couvrir moins que leur durée, ce que dit covered_s.

Champs

Les champs majeurs, mineurs et de plus longue pause viennent des notifications de la JVM, une par collecte, en millisecondes entières : leur somme approche gc_stw_ms sans l'égaler exactement, et les pauses de ZGC, de moins d'une milliseconde, y valent le plus souvent 0. ZGC et Shenandoah rapportent chaque phase de pause séparément : un cycle compte donc plusieurs pauses. Le travail concurrent du ramasse-miettes, qui n'arrête pas le serveur, n'est jamais compté comme une pause. Sur une JVM sans notifications GC (sans com.sun.management), ces champs et le débit d'allocation sont omis ; gc_stw_ms reste.

Les valeurs en tête de /api/metrics (metrics.tps, metrics.mspt, metrics.cpu_usage…) gardent leur sens : elles viennent du moniteur de ticks de VoxelBench (le TPS et le MSPT du serveur lui-même tant qu'il ne tourne pas) et du système d'exploitation, pas de ces fenêtres.

Endpoint API

L'endpoint /api/metrics renvoie les métriques actuelles du serveur en JSON. Il est disponible tant que le serveur web tourne, même quand le tableau de bord HTML est désactivé.

# Sans authentification
curl http://votre-serveur:8080/api/metrics

# Avec clé API (authentification activée)
curl -H "Authorization: Bearer VOTRE_CLE" http://votre-serveur:8080/api/metrics

Forme de la réponse (valeurs abrégées) :

{
  "timestamp": 1757937600000,
  "metrics": {
    "tps":       { "value": 19.98, "formatted": "20.0/20", "name": "TPS", "unit": "ticks/s" },
    "mspt":      { "value": 12.4, "formatted": "12.4 ms", "name": "MSPT", "unit": "ms" },
    "ram_used":  { "value": 50.0, "formatted": "2048/4096 MB (50%)", "name": "RAM Used", "unit": "%" },
    "ram_free":  { "value": 50.0, "formatted": "2048 MB (50%)", "name": "RAM Free", "unit": "%" },
    "cpu_usage": { "value": 23.5, "formatted": "...", "name": "CPU", "unit": "%" },
    "entities":  { "value": 812.0, "formatted": "...", "name": "Entities", "unit": "" },
    "chunks":    { "value": 1024.0, "formatted": "...", "name": "Chunks", "unit": "" },
    "players":   { "value": 15.0, "formatted": "...", "name": "Players", "unit": "" }
  },
  "server": { "name": "Paper", "version": "...", "maxPlayers": 100, "onlinePlayers": 15 },
  "entityBreakdown": {
    "hostile": 120, "passive": 300, "neutral": 40, "items": 250,
    "projectiles": 12, "vehicles": 5, "drops": 60, "other": 25, "total": 812
  },
  "performance": {
    "tick_time_source": "paper_tick_event",
    "heap_after_gc_mb": 812,
    "windows": {
      "10s": {
        "covered_s": 10.0, "ticks": 200, "tps": 20.0,
        "mspt_mean": 3.1, "mspt_p50": 2.8, "mspt_p95": 5.9, "mspt_p99": 8.4, "mspt_max": 11.2,
        "gc_stw_ms": 6, "gc_major_count": 0, "gc_major_pause_ms": 0, "gc_minor_count": 1, "gc_minor_pause_ms": 6,
        "gc_max_pause_ms": 6, "gc_max_pause_collector": "G1 Young Generation", "gc_max_pause_cause": "G1 Evacuation Pause",
        "alloc_rate_mb_s": 38.5, "cpu_process": 7.4, "cpu_system": 12.9
      },
      "1m": { "...": "mêmes champs" },
      "5m": { "...": "mêmes champs" },
      "15m": { "...": "mêmes champs" }
    }
  }
}

Dans metrics, la value de ram_used et de ram_free est un pourcentage du tas maximal, et leur unit vaut % ; les mégaoctets sont dans formatted. Jusqu'à VoxelBench 2.0.2, leur unit indiquait MB pour ce même pourcentage : un outil qui se fiait à unit lisait 50 Mo là où le serveur disait 50 %. Le mode push envoie le même document.

performance est décrit dans Métriques de tick, GC et CPU. Cette section vient après les autres, inchangées, et les champs qui ne sont pas mesurés sur votre serveur sont absents.

Cet endpoint est utile pour :

• Des scripts de monitoring personnalisés
• Des sources de données Grafana
• Des tableaux de bord externes
• Des systèmes d'alerte