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 legere. Lorsqu’un moniteur depasse un seuil, le moteur verifie si un moniteur amont sur la meme sonde a deja depasse un seuil dans une fenetre de temps configurable. Si c’est le cas, il journalise un indice de cause racine au lieu de traiter chaque symptome 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-01  → ERROR     (connexion refusee)
22:50  api/checkout-api  sur probe-prod-01  → ERROR     (connexion refusee)

Avec la correlation activee, les defaillances aval sont rattachees au premier depassement :

[RCA] url_shop-frontend_probe-prod-01 — [Correlated: disco/agent on probe-prod-01 breached 2m ago — possible root cause]
[RCA] api_checkout-api_probe-prod-01  — [Correlated: disco/agent on probe-prod-01 breached 2m ago — possible root cause]

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 :

Lorsqu’un moniteur url depasse un seuil, le moteur recherche un depassement db ou disco anterieur sur la meme sonde ; un depassement db recherche un depassement disco anterieur. Les types ping, tcp, nslookup et app ne figurent pas dans le modele et ne sont jamais correles.

Fonctionnement

resultat non-OK recu (url / api / db / disco)
        │
        ▼
recordRecentEvent()  ──►  fenetre glissante en memoire
        │                  (plafonnee a 500 entrees, protegee par RWMutex)
        ▼
correlateEvent()
        │  1. recherche les types amont dans le modele causal
        │  2. parcourt la fenetre pour les depassements meme-sonde,
        │     moniteur-different, dans-la-fenetre, type-amont
        │  3. retient le PLUS ANCIEN (cause racine la plus probable)
        ▼
journalise "[RCA] … [Correlated: …]" au niveau INFO

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

Fenetre recommandee

Reglez la fenetre a environ 2× le plus long intervalle de moniteur sur la sonde, afin qu’un depassement amont soit enregistre avant le declenchement des moniteurs aval.

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