Premiers pas vers Manzan

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 watcher (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 optiont « 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=3"

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)

/par