(Si ce n’est pas déjà fait, veuillez consulter le blog précédent sur Manzan pour réaliser et mieux comprendre celui ci)

Nous allons prendre l’exemple des messages INQ dans QSYSOPR pour les retranscrire dans Grafana à l’aide de Manzan

Voici d’abord comment configurer Manzan :

Tout se fait principalement dans le fichier data.ini :

[watcher_messages_INQ]
type=sql
query=SELECT MESSAGE_ID, MESSAGE_TEXT, FROM_JOB FROM QSYS2.MESSAGE_QUEUE_INFO WHERE MESSAGE_QUEUE_NAME = 'QSYSOPR' AND MESSAGE_TYPE = 'INQUIRY' AND ASSOCIATED_MESSAGE_KEY IS NULL
interval=5000
destinations=grafana
format={"msg_id": "$MESSAGE_ID$", "alerte": "$MESSAGE_TEXT$", "job_bloque": "$FROM_JOB$"}

Dans data.ini nous retrouvons le même format JSON du blog précédent. En effet Grafana gère mieux les données en JSON notamment pour le tri des différentes sources qui lui sont envoyées.

Puis voici votre dests.ini

Cette destination pointe vers une logs Grafana dans laquelle vous pouvez y passer toutes les données que vous voulez pour ensuite les trier grâce au format que vous avez défini dans votre data.ini :

[grafana]
type=loki
url=https://logs-prod-X.grafana.net
username=15****7
password=gl******************************************************

Vous trouverez tous les formats de sources ici https://theprez.github.io/Manzan/#/config/format

Vous pouvez installer Grafana en local sur une partition linux ou sur un linux externe, mais pour le moment pas sur l’ibmi… Pour notre test nous allons utiliser une version de Grafana en ligne accessible en webservice .

Dans Grafana :

Comment récupérer votre username et password dans Grafana ?

Premièrement pour l’username

Vous devez, une fois votre compte Grafana créé, vous dirigez vers la section Connection puis Data sources :

Puis vous atterrirez sur cette page :

(les rectangles noirs seront votre nom dans Grafana)

Une fois sur la page des logs (via loki qui est le service de log de Grafana) vous descendrez un petit peu pour trouver ces 2 sections :

Ce qui va nous intéresser ici est l’URL de la Connexion que vous mettrez dans votre dests.ini dans le champ url=
Mais aussi le User qui est l’identifiant de votre logs. Vous le mettrez aussi dans dests.ini dans le champ username=

Maintenant comment trouver votre password ?

Vous devez vous rendre sur la page d’acceuil de Grafana en étant connecté à votre compte puis cliquer sur My account en haut à droite

Vous atterrirez sur cette page :

2.

3.

Suite à ça vous devez copier et garder ce token pour l’utiliser dans le fichier dests.ini

Puis vous n’aurez qu’à regarder dans votre logs en pensant à surveiller que vous avez bien sélectionné vos logs loki comme montré ci dessous :

Vous pouvez ensuite créer un Dashboard dans lequel vous surveillerez tout ce que vous voudrez en créant plusieurs sources avec les données que vous enverrez dans Grafana en format JSON

Exemple :

Voici la commande en 5250 pour vous envoyer un message INQ et faire vos tests de votre côté :

SNDMSG MSG('Test Manzan messages INQ') TOUSR(QSYSOPR) MSGTYPE(*INQ)

à noter !

Le message restera visible même s’il a réçu une réponse, vous devrez l’enlever manuellement depuis 5250 pour qu’il disparaisse de Manzan et Grafana

Exemple du rendu dans le dashboard

Détail de la configuration de la table de messages INQ, quand il y en a 1 et les paramètres du dashboard:

Conclusion:

Vous pouvez utiliser Manzan , pour capter les événements souhaités sur partition IBMi, le paramétrage reste assez simple (Seulement 2 fichiers à mettre à jour)

Grafana est devenu un standard de restitution d’information, il semblait donc naturel de brancher manzan sur cette solution pour avoir un outil fiable et robuste.

A noter que dans grafana, il exite un assistant IA pour vous aider à configurer votre dasboard.

Bon tests à tous, n’hésitez pas à nous contacter pour de plus amples informations, ou à contacter https://cfd-innovation.fr/ dont on s’est librement inspiré pour cet article.

---

Aujourd’hui vous verrez comment installer, configurer et superviser les messages INQ de QSYSOPR avec Manzan pour les envoyer par mail.

Qu’est ce que Manzan ?

Manzan est un observability stack* (codé en Java) permettant de faciliter la supervisation d’une plateforme IBMi en interceptant des messages systèmes puis en les envoyant sur un serveur qui s’occupe de les rédiriger vers les destinations configurées.

*C’est un ensemble d’outils qui permettent de comprendre en profondeur ce qui se passe dans un système informatique en collectant, stockant et analysant ses métriques, logs et événements.

Il permet entre autre de :

• surveiller les messages système (QSYSOPR, QSYSMSG, QHST)
• surveiller les jobs (MSGW, CPU, statut, durée…)
• surveiller les sous‑systèmes
• surveiller les queue spools
• surveiller les ressources système (CPU, mémoire, disques)
• et bien d’autres…
• déclencher des alertes
• exécuter des actions automatiques (commandes CL, programmes CL/RPG)
• exposer les données à Grafana, Prometheus, InfluxDB, etc.

Installation de Manzan

1. Créer un répertoire « download » sur IBM i (Pour y mettre votre installeur)
2. Télécharger la dernière version du manzan-installer-v#.jar
   ou avec la commande ci dessous :
   wget https://github.com/ThePrez/Manzan/releases/download/v0.0.X/manzan-installer-v0.0.X.jar
   
3. Si vous ne l’avez pas fait directement, transférer le .jar vers IBM i
4. Lancez l’installeur avec : java -jar manzan-installer-v0.0.X.jar
5. Configurez vos fichiers .ini

(Vous aurez surement besoin de Service commander si vous ne l’avez pas déjà)

Fichiers de configuration:

Il en existe 3 :

• app.ini pour la configuration générale de Manzan (rien à toucher généralement)
• data.ini pour configurer les sources et les données à traiter
• dests.ini pour configurer les différentes sorties que Manzan va utiliser

---

app.ini

Vous n’aurez rien besoin de faire particulièrement sur celui ci à part les lignes ci dessous ci ce n’est pas déjà fait :

Vous indiquez ici la bibliothèque d’installation de Manzan

[install]
library=MANZAN

---

data.ini

Ce fichier contiendra toutes les sources que vous voudrez surveiller avec le choix du format

exemple de surveillance des messages INQ de la message queue QSYSOPR:

fichier data.ini :

[watcher_messages_INQ]
type=sql
query=SELECT MESSAGE_ID, MESSAGE_TEXT, FROM_JOB FROM QSYS2.MESSAGE_QUEUE_INFO WHERE MESSAGE_QUEUE_NAME = 'QSYSOPR' AND MESSAGE_TYPE = 'INQUIRY' AND ASSOCIATED_MESSAGE_KEY IS NULL
interval=600000
destinations=email_example
format={"msg_id": "$MESSAGE_ID$", "alerte": "$MESSAGE_TEXT$", "job_bloque": "$FROM_JOB$"}

[watcher_messages_INQ] : un id complètement arbitraire, vous pouvez le renommer comme bon vous semble

type : le type est sélectionné en fonction de la donnée à analyser. Au dessus par exemple on souhaite faire une requête pour récupérer les bonnes lignes à regarder c’est donc SQL.

query : requête SQL pour regarder les messages INQUIRY dans QSYSOPR

interval : l’interval (en ms) qui séparera chaque itération de votre requête (ici toutes les 10 minutes)

destinations : un lien vers votre fichier dests.ini dans lequel vous configurerez comment envoyer les données sélectionnées vers la/les sources que vous préciserez ici. Gardez aussi en mémoire qu’il peux y avoir plusieurs destinations séparées par des virugles.

format : Ce format de message sera son « corps ». Ce sera la façon dont vous verrez les données une fois transmises.

   (à noter que toutes vos données doivent être bornées par des $)

---

dests.ini

Ce fichier est composé de nombreuses sections qui définissent des destinations de données. Une destination est en fait un emplacement (comme un service) vers lequel les données peuvent être envoyées. Dans cet exemple j’utilise Ethereal Email qui permet d’avoir une boite mail jetable, utile pour les tests

fichier dests.ini

[email_example]
type=smtp
format=Nouveau message!! \n\n$MESSAGE_ID$ $MESSAGE_TIMESTAMP$ \n(severity $SEVERITY$): \n message : $MESSAGE_TEXT$ \n job : $FROM_JOB$
server=smtp.ethereal.email
port=587
username=exemple@ethereal.email
password=pm***********
mail.smtp.starttls.enable=true
subject=Nouveau message dans QSYSOPR
from=exemple@ethereal.email
to=exemple@ethereal.email

[email_exemple] : pareil que dans data.ini

type : même fonctionnement que dans data.ini mais cette fois ce sera la méthode d’envoi de données. Tous les types sont répertoriés ici : Types de destinations

format : même principe que dans data.ini sauf qu’ici, le format n’est pas à envoyer à destinations mais sera le format final que vous verrez, ce sera le formattage de votre « log » personnalisé (exemple en dessous)

serveur : explicitement le serveur vers lequel vous voulez envoyer votre message (ici Ethereal Email)

username : votre adresse mail

password : un identifiant propre à votre mail, vous est donnée directement à la connexion sur des services comme Ethereal Email, sinon à chercher dans vos paramètres de sécurité sur les domaine comme gmail ou hotmail.

port : port de sortie (pour envoyer) du service de mail choisi, en général ce sera toujours 587

mail.smtp.starttls.enable : sert à activer ou non le chiffrage de vos données sur le serveur

subject : l’objet du mail

from et to : respectivement l’email de l’envoyeur et du destinataire (peut être le même)

les paramètres changent en fonction de la destination, ils sont très explicites et bien documentés avec beaucoup d’exemples dans la documentation dans la catégorie des Destinations.

---

🚨Faites attention !

La QSYSOPR envoie beaucoup de messages qui ne sont pas INQUIRY donc pensez bien à faire la requête sur les messages INQ (comme dans les exemples ici). Sinon si vous utilisez votre boite mail, vous serez surement spam, c’est pourquoi dans cet exemple nous utilisons un email jetable en ligne.

---

Comment lancer Manzan ?

Il faut se mettre au bon endroit sur votre IFS, dans le répertoire où vous avez effectué l’installation de manzan en général. Soit vous y naviguez manuellement soit par VSCode vous avez cette option « Open Terminal Here » :

Ensuite une fois sur votre terminal vous taperez : sc start manzan

Vous devriez avoir ce message en vert s’afficher au bout de quelques secondes vous indiquant que c’est lancé.

(Mon Warning est dû au fait que j’ai gardé mon ancien .yaml en .old en tant que backup, vous ne devriez pas avoir ce message)

Pour être sûr que Manzan est lancé, tapez : sc check manzan
et vous devriez voir cela :

Si vous avez des problèmes ou que le serveur vous fait des timeout regardez les .yaml

le premier se trouve dans ./.sc/services/manzan.yaml

le 2e se trouve dans /opt/manzan/bin/manzan.yaml

Pensez à déclarer vos variables d’environnements comme :

MANZAN_MESSAGING_PREFERENCE=SQL MANZAN_SOCKET_PORT=8888 (prenez un port qui n’est pas déjà pris) export LC_ALL=FR_FR.UTF-8 à mettre dans votre .profile

Voici nos fichiers d’exemples

.profile

export PATH=/QOpenSys/pkgs/bin:$PATH
export LC_ALL=FR_FR.UTF-8

./.sc/services/manzan.yaml

name: Manzan
dir: /QOpenSys/etc/manzan
start_cmd: /opt/manzan/bin/manzan
check_alive: manzan
batch_mode: 'true'
sbmjob_jobname: manzan
sbmjob_opts: JOBQ(QUSRNOMAX)
environment_vars:
  - "PATH=/QOpenSys/pkgs/bin:/QOpenSys/usr/bin"
  - "MANZAN_MESSAGING_PREFERENCE=SQL"
  - "MANZAN_SOCKET_PORT=8096"
  - "MANZAN_DEBUG_LEVEL=1"

Exemples de résultats dans les mails :

Commande pour tester avec un envoie de message INQUIRY dans QSYSOPR via 5250 :

SNDPGMMSG MSG('Test message Manzan') TOMSGQ(QSYSOPR) MSGTYPE(*INQ)