Integrator

L’Integrator est un moteur de transfert de donnees a haut debit qui recoit les donnees de surveillance et les distribue vers des systemes tiers et des canaux de notification.

Vue d’ensemble

Gestion du service

Commandes CLI

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

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

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

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

# Run in foreground (Docker or debugging)
integrator run

# Remove the service
integrator uninstall

# Display help
integrator help

Configuration

Parametres principaux

{
  "name": "integrator1",
  "port": "8052",
  "logLevel": "info",
  "nbworker": "4",
  "queuesize": "10000"
}

Arborescence des repertoires

<install_dir>/
├── integrator(.exe)         # Executable
├── integrator.json          # Configuration du service
├── config/
│   ├── sec/                 # Cles RSA pour la signature JWT
│   └── ssl/                 # Certificats TLS
│       ├── certificates/
│       └── private/
├── dbs/                     # Bases de donnees cle-valeur integrees
│   ├── integrator.db        # Magasin KV principal (parametres, utilisateurs, JWT)
│   ├── event.db             # Cache des donnees de surveillance entrantes (pour les integrations pull)
│   ├── metrics.db           # Metriques systeme (CPU, memoire, uptime)
│   └── backup/              # Sauvegardes automatisees
├── log/                     # Fichiers journaux avec rotation
├── data/                    # Exports de donnees CSV/JSON
├── notif_buffer/            # File de reprise sur disque pour les notifications echouees
└── scripts/                 # Scripts d'alerte personnalises

Architecture du pool de workers

L’Integrator utilise un patron producteur-consommateur pour le traitement de donnees a haut debit :

HTTP Handler (producer)                   Workers (consumers)
     |                                         |
     |-- parse JSON, create Task -->           |
     |-- enqueue with 5s timeout -->  [Queue]  |
     |-- return HTTP 200 immediately           |
     |                                    +--> Worker 1 --> process + forward
     |                                    +--> Worker 2 --> process + forward
     |                                    +--> Worker 3 --> process + forward
     |                                    +--> Worker 4 --> process + forward

Caracteristiques principales :

• Non bloquant : les handlers HTTP retournent immediatement apres la mise en file d’attente
• Workers configurables : definis via nbworker (par defaut : 4)
• Capacite de la file : definie via queuesize (par defaut : 10 000 taches)
• Reconfiguration gracieuse : les workers vident la file avant de redemarrer avec les nouveaux parametres

Moteur de correlation inter-agents

L’Integrator embarque un moteur de correlation optionnel qui realise une analyse de cause racine. Lorsqu’un moniteur depasse un seuil, le moteur remonte une fenetre de temps configurable a la recherche d’un depassement anterieur sur un type de moniteur amont dont on peut demontrer qu’il concerne le meme hote. S’il en trouve un, il rattache une reference de cause racine a l’evenement au lieu de laisser chaque symptome circuler comme une alerte independante.

Exemple

Sans correlation, un seul hote defaillant produit trois alertes independantes :

22:48  disco/agent       sur probe-prod-01  → CRITICAL  (agent injoignable)
22:50  url/shop-frontend sur probe-prod-02  → ERROR     (connexion refusee)
22:50  api/checkout-api  sur probe-prod-02  → ERROR     (connexion refusee)

Avec la correlation activee, les defaillances aval sont rattachees au premier depassement — ici a travers deux sondes differentes, car le Sentinel Agent qui a lache en premier tourne sur l’hote meme que ciblent les controles url et api :

[RCA] url_shop-frontend_probe-prod-02 — [Correlated: disco/agent (declared) breached 2m ago — root cause]
[RCA] api_checkout-api_probe-prod-02  — [Correlated: disco/agent (declared) breached 2m ago — root cause]

La page Events du Webserver affiche alors 3 evenements → 1 incident.

Configuration

Deux methodes de configuration :

1. integrator.json — editez le fichier dans le repertoire d’installation (persiste apres redemarrage).
2. En direct depuis l’interface Webserver — allez dans Parametres → Integrator → [votre integrateur]. Le Webserver pousse les valeurs vers le endpoint /setsetting de l’Integrator et le moteur se reconfigure immediatement, sans redemarrage.

Modele causal

Le moteur utilise un graphe de dependances fixe qui definit quel type de moniteur peut etre la cause amont d’un autre :

L’empilement suit ce dont un controle depend reellement, en partant du reseau : un url en echec peut s’expliquer par tout ce qui se trouve en dessous, alors qu’un ping en echec ne peut s’expliquer que par l’hote lui-meme. Les types eum, sys, snmp, wmi et app ne font pas partie du modele et ne sont jamais correles — app est un agregat situe en aval de tout, et les autres ne sont pas raccordes a la fenetre.

Rattachement a l’hote — comment un candidat devient une cause

Etre amont et dans la fenetre ne suffit pas. Le moteur ne conserve un candidat que s’il peut etablir que les deux moniteurs concernent le meme hote, et il enregistre comment il l’a etabli dans le champ rca.link de l’evenement. Par ordre de confiance :

Les liens avec rca.targetMatch = true (declared, address, target) sont consideres comme confirmes. Un lien probe est signale comme non verifie partout ou il est affiche — icone point d’interrogation dans le tableau des evenements et sur la pastille d’incident — afin qu’un operateur distingue une vraie dependance d’une coincidence d’ordonnancement.

Rattachement au service — la cause servait-elle le port teste ?

Le rattachement a l’hote demande « est-ce la meme machine ? ». Pour une cause Sentinel missing — un processus surveille qui a disparu — cette seule question est trop grossiere : sur un hote executant une dizaine de processus surveilles, la disparition de n’importe lequel d’entre eux adopterait comme symptome toutes les erreurs tcp et api de la machine, qu’il ait ou non un rapport avec le port teste.

La preuve par le port ajoute la question plus fine : « est-ce le meme service ? »

D’ou viennent les ports des deux cotes. La sonde remonte le port auquel son controle se connecte dans hostport (proto/port, par exemple tcp/5432) : le port explicite pour les controles tcp, udp et db, et celui de l’URL (ou 443/80 selon le schema) pour url et api. Le Sentinel Agent memorise, pour chaque processus surveille, l’ensemble des ports sur lesquels il a ete observe en ecoute pour la derniere fois de son vivant, et transmet cet ensemble (procports) avec l’evenement missing. Un processus disparu n’a plus de socket a inspecter : une valeur memorisee est donc la seule preuve par le port qui puisse exister pour lui.

Le verdict est ensuite porte par rca.portEvidence :

Classement. Sans preuve, missing n’est plus prioritaire : « un processus a disparu quelque part sur cet hote » est un indice plus faible que « cet hote est sature », qui s’applique au moins a tous les services de la machine. Une cause missing ne conserve donc le niveau 0 que tant que portEvidence vaut matched ; unknown et indirect la ramenent au niveau par defaut, ou un depassement cpu, mem ou fs survenu dans la meme fenetre l’emporte au departage.

Un parc heterogene se degrade, il ne casse pas. Une sonde ancienne n’envoie pas de hostport, un Sentinel ancien n’envoie pas de procports ; les deux cas tombent dans unknown, nuance et retrograde mais jamais rejete. Un Integrator ancien ignore purement et simplement les nouveaux champs. Le seul changement de comportement sur un parc non mis a jour est la retrogradation de missing depuis le niveau 0 — qui est precisement la correction visee.

Anteriorite — la cause a-t-elle pu declencher la panne ?

Le rattachement a l’hote repond a la question « ce candidat peut-il expliquer la panne ». L’anteriorite repond a « a-t-il pu la declencher », et c’est la seule chose que la fenetre de recherche ne peut pas montrer a elle seule.

Un moniteur en echec se remonte a chaque cycle, et le moteur reevalue chacune de ces remontees. Sans regle d’anteriorite, un moniteur en echec depuis des jours adopte le premier depassement frais qui se trouve dans la fenetre a cet instant :

11 moniteurs API sur probe-win1, ERROR depuis 3j 3h  <- tous crees par le Sentinel legion-vi7
discovery-win1-missing-Notepad.exe, CRITICAL 17 min  <- meme Sentinel, processus sans rapport
-> les 11 regroupes a tort sous « disco/missing »

La propriete declaree rendait ce depassement Sentinel eligible pour tous les moniteurs qu’il a crees — a juste titre, ils surveillent bien cet hote — et rien ne verifiait si ces moniteurs etaient deja en panne avant. Ce qui est deja casse ne peut pas etre le symptome de ce qui a commence apres.

Deux tests independants, chacun suffisant pour ecarter un candidat :

Une sonde qui ne remonte aucun since desactive le second test pour cet evenement plutot que de perdre la correlation — le meme principe « ne rejeter que sur preuve positive » que suit le rattachement a l’hote. Les rejets sont journalises en niveau DEBUG :

[RCA] api_influxdb3_health — dropped disco/missing: already failing at 2026-08-02T18:03:41+02:00, candidate breached 2026-08-02T18:10:41+02:00

La charge utile rca

Les evenements correles portent un objet rca a cote des champs de resultat habituels. Le Webserver le lit pour construire la page Events :

Incidents sur la page Events

Des qu’au moins un Integrator actif a la correlation activee, la page Events du Webserver se dote d’une colonne RCA et d’un bandeau d’incidents :

• Chaque evenement est presente comme root (quelque chose pointe vers lui, avec son nombre de symptomes), symptom (nommant sa cause et de combien de minutes elle l’a precede), ou independent.
• Le bandeau met en avant le ratio qui justifie toute la fonctionnalite — 24 evenements → 9 incidents, avec le nombre de symptomes replies.
• Cliquer une pastille d’incident, ou une cellule RCA du tableau, isole cet incident et le retrie du plus ancien au plus recent : la cause racine se lit en haut, suivie de ce qu’elle a entraine. Un second clic annule.
• Une cause racine absente de la vue courante (filtree par les tags, ou traitee par un autre Integrator) forme malgre tout un incident et est signalee par une icone d’oeil barre.
• Un regroupement qui n’est pas entierement confirme — un rattachement a l’hote non verifie, ou n’importe quel symptome dont la preuve par le port vaut indirect ou unknown — porte une icone point d’interrogation sur la pastille et sur la ligne. C’est du tout ou rien : un seul symptome nuance nuance l’incident entier.

Pour savoir comment lire et piloter cette colonne au quotidien — filtres, bandeau d’incidents, isolation d’un incident — voir Page Events.

Fonctionnement

resultat non-OK recu (url / api / tcp / db / ping / nslookup / disco)
        │
        ▼
recordRecentEvent()  ──►  fenetre glissante en memoire
        │                  (plafonnee a 500 entrees, protegee par RWMutex)
        ▼
correlateEvent()
        │  1. recherche des types amont dans le modele causal
        │  2. balayage de la fenetre : depassements dans la fenetre,
        │     sur un autre moniteur, de type amont
        │  3. qualification de chaque candidat par le rattachement a l'hote
        │     (declared → address → target → probe)
        │     puis, pour une cause Sentinel a portee de service, par le port
        │     (matched → lien service | disjoints → rejet ou nuance)
        │  4. rejet des candidats posterieurs au debut de la panne
        │     (anteriorite dans la fenetre + anteriorite remontee)
        │  5. selection de la correspondance qualifiee la PLUS ANCIENNE
        ▼
rattachement de `rca` a l'evenement + journalisation "[RCA] … [Correlated: …]" en INFO

Seuls les statuts non-OK sont enregistres. Une tache cron (purgeOldRecentEvents, chaque minute) supprime les entrees plus anciennes que correlationWindowMinutes ; la fenetre est en outre plafonnee a 500 entrees.

Fenetre recommandee

Reglez la fenetre a environ 2x le plus long intervalle de moniteur afin qu’un depassement amont soit enregistre avant que les moniteurs aval ne se declenchent. Avec les liens inter-sondes, prenez le plus long intervalle sur toutes les sondes concernees, pas seulement une.

Ticketing : un incident au lieu d’un par moniteur

Avec ServiceNow active, serviceNowIncidentScope decide du nombre d’incidents que vaut une panne :

root necessite le moteur de correlation actif : sans lui rien n’est jamais un symptome, et chaque evenement ouvre donc toujours son propre incident. Voir Integration ServiceNow.

Limitations actuelles

Integrations supportees

Integrations push (l’Integrator envoie les donnees)

InfluxDB (v1.x / v2.x / v3.x)

{
  "influxDBEnabled": "true",
  "influxDBVersion": "2.x",
  "influxDBServer": "influxdb.example.com",
  "influxDBPort": "8086",
  "influxDBOrg": "myorg",
  "influxDBBucket": "mugnsoft",
  "influxDBToken": "your-token",
  "influxDBSSL": "true"
}

Les donnees sont envoyees au format line protocol :

eumResponseTime,name=MyScenario,type=eum,status=NORMAL,location=Paris responseTime=125.5,statusInt=0 1234567890000000000

Fonctionnalites : pool de connexions, logique de nouvelle tentative (2 essais, attente de 5s), support SSL.

Splunk (HTTP Event Collector)

{
  "splunkEnabled": "true",
  "splunkCollectorServer": "splunk.example.com",
  "splunkCollectorPort": "8088",
  "splunkAuthorizationToken": "your-hec-token",
  "splunkIndex": "mugnsoft",
  "splunkSSL": "true"
}

Les donnees sont envoyees sous forme d'evenements JSON vers l’endpoint Splunk HEC.

Elasticsearch

{
  "elasticEnabled": "true",
  "elasticServer": "elastic.example.com",
  "elasticPort": "9200",
  "elasticUser": "elastic",
  "elasticPwd": "password",
  "elasticSSL": "true"
}

Les donnees sont envoyees via l'API Bulk (endpoint _bulk) sous forme de documents JSON.

Kafka

{
  "kafkaEnabled": "true",
  "kafkaBrokers": "broker1:9092,broker2:9092",
  "kafkaTopic": "mugnsoft-metrics",
  "kafkaTLS": "true",
  "kafkaSASLMechanism": "SCRAM-SHA256",
  "kafkaSASLUser": "user",
  "kafkaSASLPwd": "password"
}

Supporte : TLS avec CA/certificat personnalise, authentification SASL (PLAIN, SCRAM-SHA256, SCRAM-SHA512), pool de connexions.

Canopsis

{
  "canopsisEnabled": "true",
  "canopsisServer": "canopsis.example.com",
  "canopsisPort": "8082",
  "canopsisUser": "root",
  "canopsisPwd": "password",
  "canopsisSSL": "false"
}

ServiceNow

{
  "serviceNowEnabled": "true",
  "serviceNowServer": "dev12345.service-now.com",
  "serviceNowPort": "443",
  "serviceNowUser": "mugnsoft.integration",
  "serviceNowPwd": "password",
  "serviceNowSSL": "true",
  "serviceNowResolvedState": "6",
  "serviceNowCloseCode": "Resolved by caller"
}

Contrairement aux autres destinations push, ServiceNow suit le cycle de vie complet de l’incident : il ouvre un incident lorsqu’un moniteur tombe en erreur et le resout automatiquement lorsque le moniteur se retablit. Les incidents sont correles via le champ ServiceNow correlation_id, de sorte que la resolution fonctionne meme apres un redemarrage de l’Integrator. Les actions ne sont declenchees que sur un changement de statut confirme ; les sondages non-OK repetes n’ouvrent donc jamais de doublons. La resolution automatique respecte la prise en charge ITSM : un incident deja pris par un humain (attribue / au-dela de Nouveau) est laisse ouvert avec une note de retablissement plutot que cloture automatiquement.

GLPI

{
  "glpiEnabled": "true",
  "glpiServer": "glpi.example.com",
  "glpiPort": "443",
  "glpiUser": "mugnsoft.integration",
  "glpiPwd": "password",
  "glpiAppToken": "app-token",
  "glpiSSL": "true",
  "glpiSolvedStatus": "5"
}

Comme ServiceNow, GLPI suit le cycle de vie complet du ticket : il ouvre un ticket lorsqu’un moniteur tombe en erreur et le resout automatiquement lorsque le moniteur se retablit. GLPI ne dispose pas de champ de correlation natif ; le ticket ouvert est donc retrouve via une cle embarquee inscrite dans le titre du ticket — la resolution fonctionne ainsi meme apres un redemarrage de l’Integrator. Les actions ne sont declenchees que sur un changement de statut confirme ; les sondages non-OK repetes n’ouvrent donc jamais de doublons. La resolution automatique respecte la prise en charge ITSM : un ticket deja pris par un humain (attribue / en cours / en attente) est laisse ouvert avec un suivi de retablissement plutot que cloture automatiquement. L’authentification se fait en HTTP Basic sur l’API REST de GLPI, avec un App-Token optionnel lorsque le client API GLPI l’exige.

Jira (Cloud)

{
  "jiraEnabled": "true",
  "jiraServer": "your-domain.atlassian.net",
  "jiraPort": "443",
  "jiraUser": "you@example.com",
  "jiraPwd": "api-token",
  "jiraSSL": "true",
  "jiraProjectKey": "OPS",
  "jiraIssueType": "Bug",
  "jiraResolveTransition": "Done"
}

Comme ServiceNow, Jira suit le cycle de vie complet de la demande : il ouvre une demande lorsqu’un moniteur tombe en erreur et la resout automatiquement lorsque le moniteur se retablit. Jira ne dispose pas de champ de correlation natif ; la demande ouverte est donc retrouvee via un label normalise (mugnsoft-<type>-<nom>-<sonde>) correle cote serveur par une requete JQL exacte — la resolution fonctionne ainsi meme apres un redemarrage de l’Integrator. Jira ne permet pas de fixer un statut directement ; la resolution se fait via une transition de workflow retrouvee par son nom (jiraResolveTransition, defaut Done). La resolution automatique respecte la prise en charge ITSM : une demande deja prise par un humain (attribuee / en cours) est laissee ouverte avec un commentaire de retablissement plutot que transitionnee. L’authentification se fait en HTTP Basic avec l’email du compte et un jeton d’API (Jira Cloud, API REST v3, descriptions ADF).

Integrations pull (le systeme tiers interroge l’Integrator)

Zabbix

{
  "zabbixEnabled": "true",
  "zabbixServer": "zabbix.example.com",
  "zabbixPort": "443",
  "zabbixAuthType": "token",
  "zabbixToken": "your-api-token",
  "zabbixVersion": "6.x",
  "zabbixSSL": "true"
}

Zabbix recupere les donnees en interrogeant l’API REST de l’Integrator :

GET /integrator/{bucket}/allV

Les donnees sont mises en cache dans la base cle-valeur integree de l’Integrator avec un TTL configurable.

Export de donnees

Endpoints de reception des donnees

L’Integrator expose des endpoints specifiques par type pour la reception des donnees de surveillance :

Structure des donnees entrantes

Chaque payload contient :

{
  "name": "My Monitor",
  "shortname": "mymon",
  "probe": "probe1",
  "monType": "eum",
  "timestampEpoch": 1234567890,
  "hostname": "target-host",
  "status": "NORMAL",
  "statusInt": "0",
  "location": "Paris",
  "value": 125.5,
  "transactions": { "Login": 45.2, "Search": 80.3 },
  "dnsLookup": "5.2",
  "tcpConnTime": "12.1",
  "tlsHandshake": "35.4",
  "serverTime": "52.8",
  "responseTime": "125.5",
  "emailR": "ops@example.com",
  "emailOnF": true,
  "emailOnSC": true,
  "resSC": "status_has_changed",
  "alerting": "true"
}

Alertes

L’Integrator gere les alertes de maniere centralisee lorsque les moniteurs lui sont associes.

Canaux de notification

Declencheurs d’alertes

Couleurs de statut

Tampon de notification (livraison fiable)

Si une notification ne peut etre livree — serveur SMTP indisponible, erreur Slack, webhook en timeout — l’Integrator ne l’abandonne pas. La notification echouee est ecrite sur disque puis reessayee par un worker en arriere-plan.

Chaque element tamponne enregistre le canal, l’identite du moniteur, le statut, le message, le destinataire, l’horodatage de creation et le nombre de tentatives. Le worker de reprise demarre au lancement (initNotifBuffer) et s’arrete proprement a l’extinction. Cela garantit qu’une panne transitoire d’un canal de notification ne provoque jamais la perte d’une alerte, tant que le canal se retablit dans le budget de tentatives.

API REST

Authentification

Gestion

Acces aux donnees

Utilisateurs

Systeme

Pool de connexions

L’Integrator maintient des pools de connexions pour les integrations sortantes :

Gestion des erreurs

• Logique de nouvelle tentative : 2 essais avec une attente de 5 secondes entre chaque tentative
• Non bloquant : les livraisons echouees sont journalisees mais ne bloquent pas le traitement des taches
• Verification du statut : verifie les codes de statut HTTP (200/204 pour le succes)
• Arret gracieux : les workers terminent les taches en cours avant de s’arreter

Voir aussi

• Configuration de l’Integrator – reference complete des parametres
• API HTTP de l’Integrator – documentation complete de l’API
• Guides d’integration – configuration pas a pas pour Splunk, InfluxDB, Elastic, Zabbix et Grafana
• Vue d’ensemble de la plateforme – comment l’Integrator s’integre dans l’architecture
• Flux de donnees – diagrammes du flux de donnees de surveillance et d’integration

Traductions

• en: Integrator