Monitorer IBM MQ auto-hébergé avec OpenTelemetry

Installer le collecteur NRDOT

Téléchargez et installez le package NRDOT pour votre distribution Linux. Remplacez <NRDOT_VERSION> par le dernier tag de sortie de la page nrdot-collector-releases (par exemple, v0.12.0).

• Pour Debian/Ubuntu :

  bash

  Copier

  $
  curl -LO https://github.com/newrelic/nrdot-collector-releases/releases/download/<NRDOT_VERSION>/nrdot-collector_<NRDOT_VERSION>_linux_amd64.deb
  $
  sudo dpkg -i nrdot-collector_<NRDOT_VERSION>_linux_amd64.deb

• Pour RHEL/Rocky/Amazon Linux :

  bash

  Copier

  $
  curl -LO https://github.com/newrelic/nrdot-collector-releases/releases/download/<NRDOT_VERSION>/nrdot-collector_<NRDOT_VERSION>_linux_amd64.rpm
  $
  sudo dnf install ./nrdot-collector_<NRDOT_VERSION>_linux_amd64.rpm

Configurer le collecteur NRDOT

Configurez le Collector NRDOT pour collecter les métriques IBM MQ et les envoyer à New Relic. Cette configuration gère trois tâches principales :

• Connectez-vous à vos gestionnaires de files d'attente
• Nettoyez les données
• Envoyer les données à New Relic

1. Pour créer le répertoire et le fichier de configuration du collecteur avec les autorisations requises, exécutez :

   bash

   Copier

   $
   # Config directory — group-readable by nrdot only (it will hold secrets)
   $
   sudo install -d -o root -g nrdot -m 0750 /etc/nrdot-collector
   $
   
   $
   # Create the config file with correct permissions
   $
   sudo install -o root -g nrdot -m 0640 /dev/null /etc/nrdot-collector/ibmmq-config.yaml
   $
   sudo -u nrdot ${EDITOR:-vi} /etc/nrdot-collector/ibmmq-config.yaml

2. Collez la configuration suivante dans le fichier de configuration créé, en remplaçant les espaces réservés par vos valeurs réelles :

   extensions:
     health_check:
       endpoint: 127.0.0.1:13133
   
   processors:
   
     filter/ibmmq-overhead:
       metrics:
         exclude:
           match_type: regexp
           metric_names:
             - "^go_.*"
             - "^process_.*"
             - "^promhttp_.*"
             - "^scrape_.*"
   
     filter/ibmmq-queues:
       metrics:
         datapoint:
           - 'attributes["queue"] != nil and IsMatch(attributes["queue"], "^SYSTEM\\.(ADMIN\\.|MQSC\\.|DEFAULT\\.|AUTH\\.|CHANNEL\\.|CHLAUTH\\.|CICS\\.|SYNCPOINT\\.|INTERNAL\\.|PENDING\\.|PROTECTION\\.|BROKER\\.|AMQP\\.|DOTNET\\.|REST\\.|RETAINED\\.|SELECTION\\.|DURABLE\\.|HIERARCHY\\.|DDELAY\\.)")'
           - 'attributes["queue"] != nil and IsMatch(attributes["queue"], "^SYSTEM\\.CLUSTER\\.(COMMAND|HISTORY)\\.QUEUE$")'
           - 'attributes["queue"] != nil and IsMatch(attributes["queue"], "^AMQ\\.")'
   
     resourcedetection:
       detectors: [env, ec2, system]
       system:
         resource_attributes:
           host.name:
             enabled: true
           host.id:
             enabled: true
   
     transform/ibmmq-cleanup:
       metric_statements:
         - context: resource
           statements:
             - delete_key(attributes, "server.address")
             - delete_key(attributes, "server.port")
             - delete_key(attributes, "url.scheme")
         - context: datapoint
           statements:
             # Rename the injected identity labels to their OTel dotted form — the
             # names New Relic's IBM MQ entity synthesis keys on. qmgr / queue stay raw.
             - set(attributes["target.name"], attributes["targetName"]) where attributes["targetName"] != nil
             - delete_key(attributes, "targetName")
             - set(attributes["cluster.name"], attributes["clusterName"]) where attributes["clusterName"] != nil
             - delete_key(attributes, "clusterName")
             - delete_key(attributes, "instance")
             - delete_key(attributes, "job")
   
     memory_limiter/ibmmq:
       check_interval: 1s
       limit_mib: 512
       spike_limit_mib: 256
   
     cumulativetodelta/ibmmq: {}
   
     batch/ibmmq:
       send_batch_size: 1000
       timeout: 200ms
   
   exporters:
   
     otlphttp/ibmmq:
       endpoint: ${env:NEW_RELIC_OTLP_ENDPOINT}
       headers:
         api-key: ${env:NEW_RELIC_LICENSE_KEY}
   
   receivers:
   
     prometheus/ibmmq-qm1:
       config:
         scrape_configs:
           - job_name: 'ibmmq-qm1'
             scrape_interval: ${env:IBMMQ_SCRAPE_INTERVAL:-60s}
             scrape_timeout: 15s
             static_configs:
               - targets:
                   - "${env:IBMMQ_QM1_ENDPOINT:-localhost:9157}"
                 labels:
                   targetName: "${env:TARGET_NAME}"
                   clusterName: "${env:IBMMQ_CLUSTER_NAME:-}"
   
   service:
     pipelines:
       metrics/ibmmq-qm1:
         receivers: [prometheus/ibmmq-qm1]
         processors:
           - filter/ibmmq-overhead
           - filter/ibmmq-queues
           - resourcedetection
           - transform/ibmmq-cleanup
           - memory_limiter/ibmmq
           - cumulativetodelta/ibmmq
           - batch/ibmmq
         exporters: [otlphttp/ibmmq]
   
     extensions: [health_check]

   Copier

   Important

   Ne réorganisez pas et ne supprimez pas les processeurs. L'ordre de la chaîne de processeurs est essentiel pour la synthèse d'entité. Le processeur transform/ibmmq-cleanup doit s'exécuter après le processeur resourcedetection. L'inversion de cet ordre fait que les métriques IBM MQ s'associent à la propre entité du collecteur au lieu des entités IBMMQ_MANAGER, ce qui empêche l'affichage des données sur les dashboards.

   Ce que fait cette configuration

   Cette configuration crée un pipeline qui collecte des métriques à partir des gestionnaires de files d'attente IBM MQ et achemine les données structurées vers New Relic. Chaque composant remplit une fonction spécifique :

   Composant	Description
   health_check	Fournit un point de terminaison d’intégrité à 127.0.0.1:13133 qui renvoie {"status":"Server available"} pour vérifier que le collecteur est en cours d’exécution et pour résoudre les problèmes de démarrage.
   prometheus/ibmmq-qm1	Se connecte à l'exportateur pour chaque gestionnaire de files d'attente toutes les 60 secondes pour recueillir des métriques. Chaque gestionnaire de files d'attente utilise un Récepteur indépendant ; si un gestionnaire de files d'attente tombe en panne, les Récepteurs restants continuent de fonctionner normalement. Pour ajouter d'autres gestionnaires de files d'attente, consultez la section Ajouter un autre gestionnaire de files d'attente.
   filter/ibmmq-overhead	Supprime les métriques internes de l'exportateur (telles que go_* et process_*) qui ne contiennent pas de signal IBM MQ. Cela optimise les coûts d'ingestion des données en filtrant la télémétrie inutile.
   filter/ibmmq-queues	Exclut les files d’attente système IBM MQ internes (SYSTEM.* et AMQ.*) afin que seules les files d’attente d’application deviennent des entités IBMMQ_QUEUE. Cela réduit le nombre total d’entités et concentre le monitoring sur les actifs critiques.
   transform/ibmmq-cleanup	Il s’agit d’un composant critique qui mappe les métriques aux entités IBM MQ appropriées dans New Relic. Sans ce composant, les données apparaissent comme des métriques de collecteur génériques au lieu de synthétiser les entités IBMMQ_MANAGER et IBMMQ_QUEUE avec les dashboards et alertes associés.
   memory_limiter/ibmmq	Limite l'utilisation de la mémoire à 512 Mo (avec une tolérance de pic de 256 Mo) pour éviter que le collecteur ne dépasse les limites de ressources du système.
   batch/ibmmq	Regroupe les métriques avant la transmission pour réduire la surcharge du réseau en regroupant jusqu'à 1 000 points de données par requête.
   otlphttp/ibmmq	Exporte les métriques traitées vers New Relic à l’aide de la clé de licence configurée pour l’authentification et du point de terminaison régional désigné.

   Chaque gestionnaire de files d'attente utilise un pipeline indépendant afin qu'un problème avec une instance n'affecte pas les autres. L'ordre des Processeurs est critique, ne réorganisez pas ou ne supprimez pas de Processeurs, sinon les métriques ne parviendront pas à se mapper correctement aux entités IBM MQ.

Définissez les variables d'environnement NRDOT

La configuration de votre collecteur utilise des variables d'environnement pour des valeurs spécifiques au déploiement telles que la clé de licence New Relic et les points de terminaison du gestionnaire de files d'attente. Cette approche permet de séparer les secrets des fichiers de configuration et facilite l'ajustement des paramètres sans modifier le YAML.

1. Créez un fichier d’environnement pour le collecteur NRDOT :

   bash

   Copier

   $
   # Owner nrdot, mode 0600 — this file holds the license key
   $
   sudo install -o nrdot -g nrdot -m 0600 /dev/null /etc/nrdot-collector/ibmmq-env
   $
   sudo -u nrdot ${EDITOR:-vi} /etc/nrdot-collector/ibmmq-env

2. Ajoutez votre valeur sous forme de lignes KEY=VALUE au fichier, en remplaçant les espaces réservés par vos valeurs réelles :

   # /etc/nrdot-collector/ibmmq-env
   
   # --- Required ---
   
   # New Relic ingest license key (40 chars, suffix NRAL)
   NEW_RELIC_LICENSE_KEY=<YOUR-LICENSE-KEY>
   
   # Stable host identity — first segment of every IBMMQ entity GUID
   TARGET_NAME=<YOUR-HOSTNAME>
   
   # mq-metric-samples exporter endpoints, one per queue manager
   IBMMQ_QM1_ENDPOINT=localhost:9157
   
   # --- Optional (shown with defaults) ---
   
   # OTLP endpoint: US prod default shown; For more information, refer to [New Relic OTLP endpoint](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp).
   NEW_RELIC_OTLP_ENDPOINT=https://otlp.nr-data.net:4318
   
   # Optional tag grouping for the IBMMQ_MANAGER entity (does not affect the entity GUID).
   # Leave unset to omit cluster.name (nullable); set it to group QMs under one cluster tag.
   # IBMMQ_CLUSTER_NAME=prod-mq-cluster
   
   # Scrape interval — must be >= the mq-metric-samples pollInterval (default 60s)
   IBMMQ_SCRAPE_INTERVAL=60s

   Copier

   Prudence

   Ne modifiez pas la valeur TARGET_NAME après le déploiement initial. Cette valeur forme le premier segment de chaque GUID d'entité IBMMQ_MANAGER et IBMMQ_QUEUE (target.name:qmgr). La modification de cette valeur après le déploiement crée de nouvelles entités et rend orphelines les entités existantes, ce qui casse les dashboards et les alertes associés. Sélectionnez une chaîne stable lors de la configuration initiale, telle que le QMID du gestionnaire de files d'attente. Pour plus d'informations, voir Le modèle d'entité IBM MQ.

   Définissez les variables d'environnement suivantes dans votre shell pour vérifier la configuration avant de démarrer le collecteur :

   Variable	Requis	Description
   NEW_RELIC_LICENSE_KEY	Oui	Votre clé de licence d'ingestion New Relic.
   TARGET_NAME	Oui	Un identifiant pour votre hôte, tel que le nom d’hôte ou l’ID du gestionnaire de files d’attente. Ne modifiez pas ceci après le déploiement initial, car cela fait partie des ID de votre entité.
   IBMMQ_QM1_ENDPOINT	Oui	Emplacement de l'exportateur de votre premier gestionnaire de files d'attente. Par exemple, localhost:9157 s'il s'exécute sur le même hôte.
   NEW_RELIC_OTLP_ENDPOINT	Non	Point de terminaison OTLP New Relic pour votre région. Pour plus d'informations, consultez le point de terminaison OTLP de New Relic.
   IBMMQ_CLUSTER_NAME	Non	Nom du Cluster pour regrouper vos gestionnaires de files d'attente dans New Relic.
   IBMMQ_SCRAPE_INTERVAL	Non	Intervalle de collecte pour exporter les métriques vers New Relic. L'intervalle de collecte par défaut est de 60 secondes.

Configurer le service systemd NRDOT

1. Créez un fichier drop-in systemd pour charger les fichiers de configuration et d'environnement.

   bash

   Copier

   $
   sudo mkdir -p /etc/systemd/system/nrdot-collector.service.d
   $
   sudo tee /etc/systemd/system/nrdot-collector.service.d/ibmmq.conf > /dev/null << 'EOF'
   $
   [Service]
   $
   EnvironmentFile=/etc/nrdot-collector/ibmmq-env
   $
   ExecStart=
   $
   ExecStart=/usr/bin/nrdot-collector --config /etc/nrdot-collector/ibmmq-config.yaml
   $
   MemoryMax=1G
   $
   LimitNOFILE=65536
   $
   NoNewPrivileges=true
   $
   ProtectSystem=strict
   $
   ProtectHome=true
   $
   EOF

   La ligne ExecStart= vide efface la commande par défaut, et la deuxième ligne définit la commande personnalisée. Cela empêche le collecteur de démarrer deux fois. Les autres paramètres chargent le fichier d'environnement, limitent l'utilisation de la mémoire et améliorent la sécurité.

2. Après avoir créé le drop-in, vérifiez que systemd peut l'analyser sans erreurs :

   bash

   Copier

   $
   sudo systemd-analyze verify /etc/systemd/system/nrdot-collector.service
   $
   # No output means no syntax errors

Démarrer le collecteur NRDOT et vérifier

1. Démarrez le collecteur et activez-le pour qu’il s’exécute automatiquement au démarrage :

   bash

   Copier

   $
   sudo systemctl daemon-reload
   $
   sudo systemctl enable --now nrdot-collector.service
   $
   sudo systemctl status nrdot-collector.service --no-pager

   La commande status devrait afficher Active: active (running). Si vous voyez Active: failed, vérifiez les logs avec journalctl -u nrdot-collector.service -n 200 --no-pager.

2. Vérifiez que le collecteur est en bon état :

   bash

   Copier

   $
   curl -sS http://127.0.0.1:13133
   $
   # Expected: {"status":"Server available", ...}

3. Confirmez que vos métriques IBM MQ sont transmises à New Relic. Attendez 60 secondes après le démarrage du collecteur, puis vérifiez vos données à l'aide des requêtes de vérification dans Trouver et interroger vos données.

Affichez vos données dans New Relic

Une fois que votre collecteur est en cours d'exécution et que les métriques circulent, vous verrez vos gestionnaires de files d'attente en tant qu'entités IBMMQ_MANAGER dans New Relic, avec leurs files d'attente en tant qu'entités IBMMQ_QUEUE enfants. Pour plus de détails sur la recherche de vos données, l'exécution de requêtes et la configuration de dashboards et d'alertes, consultez Rechercher et interroger vos données.