gilles/nano_metrics
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 16 Wiki Activity
Files
a53923fd8e52e75ffbfa53061c922b723fc6d840
nano_metrics/CLAUDE.md
T
Gilles Soulier 8e44b2f335 Initial commit: CLAUDE.md + spec de design Nanometrics 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-22 07:57:09 +02:00

9.0 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Langue : réponds toujours en français.

Skills et outils à utiliser

Toujours utiliser les skills appropriés avant d'agir :

  • brainstorming — avant toute création de feature, composant ou choix d'architecture
  • writing-plans / executing-plans — pour toute tâche multi-étapes, planifier avant de coder
  • test-driven-development — avant d'écrire le code d'implémentation
  • systematic-debugging — avant de proposer un fix sur un bug ou test qui échoue
  • WebSearch — rechercher la doc, les crates Rust, les packages Go, les conventions
  • verification-before-completion — vérifier que ça fonctionne réellement avant de déclarer terminé
  • utiliser rtk pour reduire la consommation de token

Vue d'ensemble du projet

Nanometrics — système client-serveur de surveillance matérielle (CPU, RAM, disque) avec empreinte quasi nulle sur les machines Debian.

Trois composants :

  • Agent Rust (agent/) — collecte les métriques, envoie via UDP et/ou MQTT
  • Serveur Go (server/) — reçoit les données, expose /metrics Prometheus + API REST + WebSocket
  • Dashboard web (dashboard/) — UI servi par Nginx dans Docker, temps réel via WebSocket

Un README.md doit être écrit à la racine : installation de l'agent et du serveur, liste des features.

Métriques collectées

Métriques actuelles : hostname, ip, memory_free, memory_used, hdd_total, hdd_free, hdd_used, cpu_percent, status (online/offline), uptime.

L'agent a une architecture modulaire : chaque métrique est un module indépendant activable/désactivable via config. Ajouter une métrique = ajouter un module sans toucher au cœur.

Commandes de build

# Agent Rust
rtk cargo build --release --manifest-path agent/Cargo.toml
rtk cargo test --manifest-path agent/Cargo.toml
rtk cargo clippy --manifest-path agent/Cargo.toml

# Serveur Go
rtk go test ./server/...

Agent Rust — contraintes non négociables

  • Pas de runtime async (pas de Tokio). Boucle mono-thread avec std::thread::sleep pour les fréquences différenciées (CPU 2s, réseau/uptime 10s, disque 60s).
  • sysinfo avec default-features = false — empêche les threads de fond qui gonflent la RAM.
  • Profil release : strip = true, opt-level = "z", lto = true.
  • Config via config.toml (serde) — paramètres serveur, métriques activées, protocoles. Rien de codé en dur.
  • Deux protocoles supportables simultanément :
    • UDP — fire-and-forget JSON vers server_ip:server_port
    • MQTT — bidirectionnel vers broker mqtt_host:mqtt_port (défaut 10.0.0.3:1883, sans auth)
  • Échange de config au démarrage : à la connexion, l'agent envoie un message "birth" et récupère sa config depuis le serveur (push/pull bidirectionnel). Le serveur peut envoyer une nouvelle config à l'agent à tout moment.
  • Architecture future : prévoir un canal de réception de commandes (reboot, shutdown, screen off, update, upgrade, shell cmd…) sans refonte du cœur.

MQTT — options de l'agent

  • Auto-discovery : publication du topic de découverte compatible Home Assistant
  • Birth message : publié à la connexion sur {topic_base}/{hostname}/status = online
  • Last Will message : configuré au connect, publié automatiquement par le broker si l'agent disparaît = offline
  • Topic base configurable (défaut : nanometrics/agents)

Serveur Go — contraintes non négociables

  • Déployé dans Docker — docker-compose.yml fourni avec Nginx pour le dashboard.
  • Goroutine par datagramme UDP reçu pour la désérialisation JSON.
  • Écoute MQTT en parallèle (subscribe sur {topic_base}/#).
  • Métriques exposées via github.com/prometheus/client_golang (Gauges) sur /metrics.
  • API REST — endpoints pour le dashboard : agents, métriques, historique, config agents, icônes.
  • WebSocket — push temps réel vers le dashboard (mise à jour des métriques et changements de statut).
  • SQLite — persistance des métriques historiques avec rétention configurable.
  • Config agent : le serveur stocke la config de chaque agent (métriques actives, protocoles, options MQTT). Envoyée à l'agent au birth et pushée si modifiée depuis le dashboard.

Déploiement systemd (agent)

Le fichier .service doit utiliser :

  • DynamicUser=yes — utilisateur éphémère, ProtectSystem=strict + ProtectHome=read-only automatiques
  • ConfigurationDirectory= — accès sécurisé au TOML de config

Dashboard web — spécifications UI

Grille principale

  • Une tuile rectangulaire par agent — grille auto-fill minmax(220px, 1fr) responsive.
  • Métriques en icônes (pas de texte) avec tooltips sur chaque icône.
  • Jauges barre pour CPU, RAM, disque dans les tuiles.
  • Effets : halo lumineux au survol (couleur selon statut), pression 3D au clic.
  • Tooltips globaux : positionnés en position:fixed via JS (jamais clippés).
  • Jusqu'à 20+ agents — taille de tuiles configurable.

SMART disque

  • L'agent vérifie si smartctl est disponible sur la machine cible.
  • Si disponible : collecte l'état SMART simplifié (PASSED / FAILED + température + reallocated sectors).
  • Le popup détail affiche un bouton SMART dans la section Stockage (couleur ok/warn/err selon état).
  • Clic sur le bouton → popup SMART complet, lisible par un non-expert, en français : état général, température, durée de vie estimée, secteurs défectueux, explications simples.

Popup détail agent (clic sur tuile)

  • Redimensionnable en largeur et hauteur — dernière taille sauvegardée sur le serveur.
  • Pas de bouton "Fermer" — uniquement la croix en haut à droite.
  • Icône agent cliquable pour upload custom (SVG/JPG/PNG/WEBP, redim. canvas max 128×128 px ratio préservé, sauvegardée sur le serveur).
  • KPIs actuels + courbes historiques (SVG) pour CPU et RAM.
  • Stockage en jauges barre.
  • Protocoles actifs affichés en badges.
  • Bouton icône fa-gears en bas à droite → ouvre le popup de configuration de l'agent.

Popup configuration agent

  • Accessible depuis le popup détail via l'icône gears (bas à droite).
  • Tableau métriques — 3 colonnes : MÉTRIQUE / UDP / MQTT — une case à cocher par métrique par protocole, indépendantes. Pas d'activation générale du protocole.
    • Métriques : cpu, memory, disk, smart, uptime, network, temperature
    • Chaque case peut être cochée/décochée indépendamment (ex : CPU via UDP uniquement, température via MQTT uniquement)
  • Paramètres MQTT : broker, port, topic base, auto-discovery (Home Assistant) toggle, birth message toggle, last will toggle.
  • Commandes distantes : section affichée mais désactivée (bientôt) — reboot, shutdown, screen off, update, upgrade, shell cmd.
  • Bouton "Envoyer à l'agent" — pousse la config via API REST → serveur → agent.

Header

  • Logo + LED animée + compteurs agents (total / ok / warn / err).
  • Bouton thème clair/sombre.
  • Bouton configuration interface (taille tuiles, texte, seuils, rétention historique) — config sauvegardée sur le serveur.

Footer (status bar)

  • Mode LIVE en fond accent (style tmux).
  • CPU et RAM du serveur avec mini-jauges.
  • Horodatage de la dernière actualisation.

Stockage local des assets

Toutes les ressources web versionnées localement — pas de CDN en production :

dashboard/
├── fonts/          (Inter, JetBrains Mono, Share Tech Mono)
├── vendor/
│   └── fontawesome/
├── design_system/
│   ├── tokens/tokens.css
│   └── components/ui-kit.jsx

Design System — règles obligatoires

Toute UI utilise design_system/. Lire design_system/consigne_design_system.md entièrement avant d'écrire du code UI.

Règles clés :

  • Toujours les variables CSS — jamais de hex en dur.
  • data-theme obligatoire sur <html>. Sans ça, l'UI casse silencieusement.
  • Composants dans ui-kit.jsx avant d'en créer de nouveaux.
  • Icônes : Font Awesome via <Icon name="…"> uniquement — pas d'emoji, pas de SVG inline.
  • Polices : Inter (UI), JetBrains Mono (valeurs numériques), Share Tech Mono (logs/terminal).
  • Labels : uppercase + letter-spacing: 0.08em.
  • Border-radius : tuiles 10-12px, boutons 8px, pastilles 999px.
  • user-select:none : uniquement sur les éléments purement interactifs (.hbtn, .btn, .pop-close, .cbox, .btn-agent-cfg, .tile-head, .tile-foot). Jamais sur les conteneurs de contenu : le texte (hostname, IP, valeurs, labels) et les icônes doivent rester sélectionnables.

Tokens de statut

Token Usage
--ok état nominal
--warn attention, seuil élevé
--err erreur, alerte critique
--accent action principale (orange Gruvbox)
--blue datavis CPU / secondaire
--purple MQTT / datavis tertiaire
Reference in New Issue View Git Blame Copy Permalink