Discovery Agent

Le Discovery Agent surveille l’hote sur lequel il s’execute, decouvre les services, collecte les metriques systeme et processus, et genere des alertes basees sur des seuils.

Vue d’ensemble

Gestion du service

Commandes CLI

# Install as service and register with the Webserver
discovery_agent install <webserver_ip>:<port>

# Re-register with the Webserver
discovery_agent register <webserver_ip>:<port>

# Migrate to a new Webserver
discovery_agent migrate <webserver_ip>:<port> <jwt_token>

# Start / Stop / Restart
discovery_agent start
discovery_agent stop
discovery_agent restart

# Run in foreground
discovery_agent run

# Remove the service
discovery_agent uninstall

Configuration

Parametres principaux

{
  "name": "agent1",
  "port": "8070",
  "webserver": "192.168.1.100:8050",
  "integratorEndPoint": "192.168.1.100:8052",
  "location": "Datacenter-1",
  "sched": "5MIN",
  "processes": "nginx,mysql,java",
  "ports": "80,443,3306",
  "logLevel": "info"
}

Options de planification

Arborescence des repertoires

<install_dir>/
├── discovery_agent(.exe)     # Executable
├── discovery_agent.json      # Configuration du service
├── config/
│   ├── sec/                  # Cles RSA
│   └── ssl/                  # Certificats TLS
├── data/
│   ├── process_list.txt      # Noms des processus surveilles
│   ├── port_list.txt         # Ports reseau surveilles
│   ├── process_thresholds.json   # Configuration des seuils par processus
│   ├── system_thresholds.json    # Configuration des seuils systeme
│   ├── discover_metrics.json     # Dernieres metriques collectees
│   └── alerts.json           # Alertes generees
├── dbs/                      # Bases de donnees cle-valeur integrees
│   ├── discovery.db          # Donnees de decouverte principales
│   ├── metrics.db            # Historique des metriques
│   ├── process.db            # Donnees des processus
│   ├── system.db             # Donnees systeme
│   └── backup/               # Sauvegardes automatisees
└── log/                      # Fichiers journaux avec rotation

Mecanismes de decouverte

Decouverte des processus

Le Discovery Agent surveille les processus par nom. Configurez les processus a surveiller :

Methode 1 : Fichier de configuration

{
  "processes": "nginx,mysqld,java,python3"
}

Methode 2 : Fichier de liste de processus (data/process_list.txt)

nginx:web,production
mysqld:database,production
java:application
python3.12:scripts

Format : nomprocessus[.exe]:tag1,tag2 (separe par deux-points, avec tags optionnels)

Decouverte des ports

Surveillez quels processus ecoutent sur des ports specifiques :

Fichier de configuration :

{
  "ports": "80,443,3306,5432,8080"
}

Fichier de liste de ports (data/port_list.txt) :

80
443
3306
5432

L’agent associe les ecouteurs de ports aux noms de processus via l’enumeration des connexions TCP.

Decouverte du trafic reseau

Utilise la capture de paquets (pcap) via la bibliotheque gopacket pour l’analyse du trafic en direct :

• Capture les paquets sur toutes les interfaces reseau
• Duree configurable via discoCapInterval
• Agrege le trafic par identifiant de processus (PID)
• Calcule la bande passante en kbits/s (entrant/sortant)
• Genere un graphique de topologie reseau au format Cytoscape pour la visualisation

L’interface web affiche ce graphe avec des couleurs de liens pilotees par la gravite du trafic et des couleurs de libelles pilotees par la famille de protocole — voir Lire le graphe de decouverte.

La capture de paquets est une dependance d’execution

Les valeurs de bande passante proviennent des paquets captures : l’hote doit donc disposer d’un runtime pcap et du privilege permettant de l’ouvrir. C’est une exigence d’execution uniquement — rien n’est necessaire pour compiler ou mettre a jour l’agent.

ln -s /usr/lib64/libpcap.so.1 /usr/lib64/libpcap.so.0.8

Ce que l’on perd sans capture

L’echec est silencieux et l’agent reste actif. Il journalise qu’il poursuit sans capturer de paquets et continue de collecter tout le reste :

• Conserve — l’inventaire complet des connexions (IP et port local/distant, PID, nom du processus, sens, interface). La carte de topologie reste intacte.
• Conserve — les libelles de protocole, mais deduits du seul numero de port et du nom de processus, sans preuve sur le fil. Tous relevent du niveau de confiance devine, ce qui explique que la categorie Unidentified du filtre Proto grossisse sur un hote sans capture.
• Perdu — toutes les valeurs en kbits/s. Le trafic entrant / sortant par processus reste a 0, l’usage des liens de la carte reste a 0, et les seuils de trafic ne peuvent jamais se declencher.

Les metriques qui ne dependent pas de la capture ne sont pas affectees : netBytesRate et netTxDrops par interface proviennent des compteurs de l’OS, tout comme les metriques CPU, memoire, disque et systeme de fichiers.

Le statut de capture est remonte : un zero n’est jamais ambigu

Une bande passante a 0 a la meme apparence qu’un lien reellement inactif ou qu’une absence de pilote pour la mesurer. Chaque cycle de collecte remonte donc un statut de capture avec les metriques, que l’interface web expose :

• un badge ambre No packet capture dans la barre d’outils du graphe de decouverte, dont l’infobulle reprend telle quelle la raison remontee par l’agent (pas de runtime pcap, permission refusee, aucune interface exploitable) ;
• une ligne en tete du menu deroulant du filtre Proto, qui explique la categorie Unidentified la ou on la rencontre ;
• les infobulles des liens affichent “not measured — no packet capture” au lieu de 0.000 kbits/s, et leur mini-courbe de bande passante est supprimee plutot que tracee a plat a partir d’un historique de zeros ;
• dans le rapport processus, les pastilles de seuil Traffic In et Traffic Out ainsi que leurs deux panneaux de graphique portent une icone d’avertissement. Aucune autre metrique de ce rapport n’est concernee.

Lorsque plusieurs agents sont fusionnes sur une meme carte (niveau 2), le badge signifie qu'au moins un agent contributeur n’a pas pu capturer, et le libelle le precise.

Un 0.000 reel reste affiche quand la capture fonctionne — celui-la est une mesure.

Parametres de comportement de la capture

Les deux drapeaux sont relus au debut de chaque cycle de collecte : une modification prend effet au cycle suivant, sans redemarrage. Une cle absente ou illisible retombe sur le defaut ci-dessus, afin que les configurations ecrites avant l’existence de ces cles conservent leur comportement.

Moniteurs delegues (controles URL / API / port)

Au-dela des metriques de l’hote, un agent de decouverte peut definir des controles synthetiques — urls, apis, pings, nslookups, tcps, dbs et syss — directement dans sa configuration. L’agent n’execute pas ces controles lui-meme ; il les delegue a une ou plusieurs sondes Monitor nommees dans probeEndPoint.

{
  "appName": "Shop",
  "probeEndPoint": "probe1,probe-win2",
  "ports": "80,443,3306",
  "urls": [{ "name": "shop-home", "url": "https://shop.example.com/" }],
  "apis": [
    {
      "name": "checkout-api",
      "url": "https://api.example.com/health",
      "typeApi": "GET"
    }
  ]
}

Cela permet de decrire toute la surface de service d’un hote (sante systeme et ses endpoints) au meme endroit, tandis que l’execution reelle des URL/API se fait sur une sonde ayant un acces reseau aux cibles.

Metriques collectees

Metriques systeme

Metriques par processus

Activation/desactivation des metriques

Chaque metrique peut etre activee ou desactivee individuellement :

{
  "discoCPUGMonEnabled": "true",
  "discoMEMGMonEnabled": "true",
  "discoLoadAvg5minGMonEnabled": "true",
  "discoCPUPMonEnabled": "true",
  "discoMEMPMonEnabled": "true",
  "discoSWAPPMonEnabled": "false"
}

Configuration des seuils

Seuils fixes

Definissez des valeurs de seuil explicites par metrique :

{
  "discoCPUGFixedThreshCri": "95",
  "discoCPUGFixedThreshMaj": "85",
  "discoCPUGFixedThreshMin": "75"
}

Seuils automatiques

Laissez l’agent calculer les seuils a partir des donnees historiques :

{
  "discoCPUPAutoThreshold": "true",
  "discoMEMPAutoThreshold": "true"
}

Les seuils automatiques utilisent une analyse statistique (ecart-type) des metriques historiques pour definir dynamiquement les valeurs de seuil.

Quand le seuil automatique est active pour une metrique, laissez les champs *FixedThresh* correspondants vides (""). L’interface web affiche ces champs avec ∞ : pendant le calcul de la baseline (periode de warm-up), aucune alerte n’est emise pour cette metrique.

Seuils de trafic

Seuils de trafic reseau par processus avec operateurs directionnels :

{
  "trafficThresholds": {
    "nginx": {
      "operator": ">",
      "critical": 10000,
      "major": 5000,
      "minor": 1000
    }
  }
}

Operateurs : > (alerter lorsque au-dessus) ou < (alerter lorsque en dessous).

Alertes

Niveaux de statut des alertes

Canaux de notification

Identiques aux autres composants :

Temporisation des alertes

Routage des alertes

Les alertes peuvent etre acheminees de deux facons :

1. Via l’Integrator (recommande) – le Discovery Agent envoie les metriques a l’Integrator, qui gere les alertes de maniere centralisee
2. Alertes locales – le Discovery Agent envoie les alertes directement via les canaux configures (lorsqu’aucun Integrator n’est configure)

La concurrence est controlee par des semaphores : 20 goroutines simultanees pour la communication avec l’Integrator, 10 pour les alertes locales.

Flux d’execution

Cron trigger (every N minutes)
  |
  v
execDiscovery()
  |
  v
runDiscoveryMetrics()
  ├── CollectSystemMetrics()    --> CPU, memory, load, FS, sockets
  ├── CollectProcessMetrics()   --> per-process CPU, memory, I/O, traffic
  ├── CollectNetworkMetrics()   --> pcap traffic capture, connections
  └── GenerateCytoscapeData()   --> network topology graph
  |
  v
Write data/discover_metrics.json + data/alerts.json
  |
  v
discoveryDataFile()
  ├── processMetricsKV()    --> evaluate per-process thresholds
  ├── systemMetricsKV()     --> evaluate system thresholds
  └── Route alerts:
       ├── goDataSent2Integrator()   (if Integrator configured)
       └── goHandleAlerting()         (local fallback)

Taches cron en arriere-plan

Metriques par element et peripheriques disparus

Les metriques disque et reseau sont stockees par element — une serie par disque, point de montage ou interface. L’agent cree une serie a la premiere apparition de l’element et ne la supprime jamais : un disque USB monte une seule fois, ou une carte reseau que l’OS a depuis renommee, laisse donc une serie qui ne recoit plus d’echantillon.

Deux mecanismes les ecartent :

• Les rapports les excluent. Pour les elements auto-decouverts (disques, interfaces reseau), une serie n’ayant produit aucun echantillon dans la fenetre demandee est entierement omise du rapport : l’interface cesse d’afficher un panneau « aucune donnee » pour un disque qui n’existe pas. Un element simplement inactif continue d’ecrire un echantillon a chaque cycle et n’est pas concerne.
• La retention les supprime. La purge nocturne supprime tout element dont l’echantillon le plus recent precede la fenetre de retention, ainsi que ses entrees de changement et de statut.

La retention couvre toutes les metriques

La purge des metriques parcourt l’ensemble du magasin plutot qu’une liste figee de noms, car le jeu de metriques varie selon la plateforme (ni load average ni I/O wait sous Windows) et s’enrichit a chaque version.

Endpoints de l’API REST

Authentification

Decouverte

Acces aux donnees

Parametres

Sante

Sauvegarde et restauration

Certificats

Journaux

Traductions

• en: Sentinel Agent