Installation de l'agent hôte sur IBM i

Assurez-vous que les prérequis suivants sont respectés :

• IBM i 7.4 ou version ultérieure

• Veillez à installer les programmes sous licence suivants dans votre système :

  • 5770-SS1 option 30, QSHELL
  • 5770-SS1 option 33, PASE
  • 5770-JV1, IBM Developer Kit for Java : option 17 pour Java 8 ou option 19 (sur IBM i 7.5 et versions antérieures) pour Java 11.

• Installer certains paquets open source dans IBM Portable Application Solutions Environment (PASE) pour i. Pour plus d'informations sur les paquets open source sur IBM i, voir Pile RPM pour IBM i dans les versions de support standard. Vous pouvez utiliser le système de gestion des paquets open source d' IBM i Access Client Solutions (ACS) pour installer ces paquets dans PASE. Les paquets nécessaires sont installés par défaut. Vous devez également installer les paquets suivants :

  • Bash
  • Tar-GNU (pour extraire l'archive de l'agent).

Vérifiez si la surveillance locale d' IBM i. peut répondre à vos besoins en consultant la liste non exhaustive suivante des capteurs pris en charge, qui peuvent être détectés automatiquement sur IBM i. Si ce n'est pas le cas, utilisez la surveillance à distance de IBM i. Pour plus d'informations, consultez la section « Surveillance des instances d' IBM i ».

• Apache Tomcat
• Script d'automatisation
• DB2 for IBM i
• IBM i
• IBM MQ
• Machine virtuelle Java
• Node.js
• Python
• Spring Boot
• WebSphere Application Server
• WebSphere Liberty

Pour collecter les métriques pour WebSphere Liberty, vous devez activer la fonctionnalité monitor-1.0. Pour activer cette fonction, ouvrez le fichier server.xml, qui se trouve dans le répertoire <websphere-liberty_install_dir>/usr/servers/<specific_server>/, puis ajoutez les lignes suivantes au fichier :

<featureManager ...>
    ...
    <feature>monitor-1.0</feature>
    ...
</featureManager>
 

IBM i 7.6 introduit l'authentification multifactorielle (MFA) pour les profils utilisateur. L'agent « Instana » peut être exécuté par un profil utilisateur, que l'authentification multifactorielle (MFA) soit activée ou non. Pour plus d'informations, consultez la section « Démarrage de l'agent hôte ».

Pour surveiller les technologies basées sur l' Java, l'agent Instana doit basculer vers le profil utilisateur qui exécute la tâche Java, si celle-ci est exécutée par un utilisateur différent de l'agent. En général, l'agent d' Instana s peut basculer vers un profil utilisateur compatible avec l'authentification multifactorielle (MFA) sans avoir besoin du code TOTP associé à ce profil. Cependant, l'agent ne peut pas passer à un profil utilisateur dont l'accès à l'identifiant d'utilisation de la QIBM_RUN_UNDER_USER_NO_AUTH fonction est refusé. Par défaut, tous les profils utilisateur (avec ou sans authentification multifactorielle) ont accès à cet identifiant d'utilisation de la fonction, ce qui permet à l'agent d' Instana s de se connecter à leurs JVM. Pour plus d'informations, consultez l'ID d'utilisation de la fonction QIBM_RUN_UNDER_USER_NO_AUTH.

Pour plus d'informations sur la surveillance à distance d' IBM i. avec l'authentification multifactorielle (MFA), consultez la note relative à la MFA.

Pour installer l'agent hôte sur IBM i, effectuez les étapes suivantes :

1. Téléchargez l'archive de l'agent sur votre système local :

   1. Dans la barre de navigation de l'interface utilisateur d' Instana, cliquez sur Plus > Agents > Installer des agents.

   2. Sur la page du catalogue de déploiement de l'agent, cliquez sur la tuile IBM i - Archive (tar.gz).

   3. Sélectionnez le mode de conditionnement de l'agent, Dynamic ou Static. Pour plus d'informations sur les agents hôtes dynamiques et statiques, consultez la section Types d'agents hôtes.

   4. Cliquez sur le lien de téléchargement pour IBM i pour télécharger le fichier tar.gz.

2. Créez un répertoire IFS cible (par exemple, /opt/instana/) sur le système IBM i en exécutant la commande suivante :

   MKDIR DIR('/opt/instana')
    

3. Déplacez l'archive de l'agent dans le répertoire que vous avez créé à l'étape 2. Vous pouvez utiliser FTP ou l'interface IFS d'ACS pour déplacer l'archive de l'agent.

4. Extrayez l'archive de l'agent sur le système IBM i en exécutant les commandes suivantes :

   CALL QP2TERM
    

   cd <instana-directory>
    

   /QOpenSys/pkgs/bin/tar -xzf instana-agent-ibmi-ppc.tar.gz
    

   Après avoir extrait l'archive de l'agent, un nouveau répertoire <instana-directory>/instana-agent est créé. Par exemple, /opt/instana/instana-agent.

5. Configurez l'agent pour qu'il pointe vers votre serveur Instana à l'aide du *instanaAgentDir*/etc/instana/com.instana.agent.main.sender.Backend.cfg fichier. Ce fichier contient les paramètres utilisés par l'agent hôte pour communiquer avec le backend Instana, notamment host et key. Pour plus d'informations, consultez la section « Configuration du backend d' Instana ».

L'agent hôte est maintenant installé et configuré sur votre système IBM i.

Après avoir installé l'agent hôte, vous pouvez administrer l'agent hôte, par exemple vérifier l'état de l'agent ou le démarrer.

Vous pouvez également configurer l'agent selon vos besoins. Pour plus d'informations, consultez la section « Configuration de l'agent hôte ».

Vous pouvez utiliser Ansible pour automatiser l'installation de l'agent hôte sur plusieurs nœuds IBM i à l'aide du playbook suivant. Vous pouvez exécuter ce playbook sur un serveur de type UNIX sur lequel Ansible est installé. Ce playbook crée automatiquement le répertoire de destination, copie et extrait l'archive de l'agent, et démarre l'agent sur tous vos systèmes IBM i.

Pour plus d'informations sur les conditions préalables et la gestion des systèmes IBM i avec Ansible, voir Power IBM i collection pour Ansible. Pour découvrir d'autres exemples d' IBM i, consultez l'article « Automatisez vos tâches d' IBM i avec Ansible ».

Pour automatiser l'installation de l'agent hôte en utilisant Ansible, effectuez les étapes suivantes :

1. Enregistrez la configuration du playbook suivante dans un fichier. YAML, par exemple playbook.yml, dans un répertoire de votre système.

   ---
   - hosts: ibmi
     collections:
     - ibm.power_ibmi
     tasks:
     - name: Create Instana Directory
       ansible.builtin.file:
         path: /opt/instana
         state: directory
     - name: Remove Old Instana Agent files
       ansible.builtin.file:
         path: '{{ item }}'
         state: absent
       with_items:
         - /opt/instana/instana-agent
         - /opt/instana/instana-agent-ibmi-ppc.tar.gz
     - name: Copy Agent Tar to System
       ansible.builtin.copy:
         src: ./instana-agent-ibmi-ppc.tar.gz
         dest: /opt/instana/
     - name: Extract Instana Agent
       shell:
         cmd: tar -xzf /opt/instana/instana-agent-ibmi-ppc.tar.gz
     - name: Run Instana Agent in QUSRWRK
       ibmi_cl_command:
         cmd: sbmjob cmd(qsh cmd('export JAVA_HOME=/QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit; exec bash /opt/instana/instana-agent/bin/start')) jobq(QUSRNOMAX) LOG(*JOBD *JOBD *NOLIST)
    

2. Téléchargez l'archive de l'agent en suivant l'étape 1 de la section Installation manuelle de l'agent, et enregistrez-la dans le même répertoire que le playbook.

3. Créez un fichier inventory.ini, qui répertorie tous les nœuds IBM i où vous souhaitez installer l'agent, et enregistrez-le dans le même répertoire que le playbook. Pour plus d'informations sur ce inventory.ini fichier, consultez la section « Créer votre inventaire ».

4. Exécutez le playbook depuis votre serveur Ansible en utilisant la commande suivante :

   ansible-playbook -i inventory.ini playbook.yml
    

L'agent est déployé sur tous les systèmes IBM i spécifiés dans le fichier inventory.ini.

Après avoir installé l'agent, vous pouvez le configurer selon vos besoins. Les configurations peuvent être appliquées lors de l'exécution de l'agent, et les changements sont immédiatement appliqués. Pour plus d'informations, consultez la section « Configuration de l'agent hôte ».

Une fois l'agent hôte installé, vous pouvez vérifier son état dans l'interface utilisateur d' Instana. Pour plus d'informations, voir Vérification de l'état de l'agent hôte.

Pour démarrer l'agent hôte, exécutez la commande suivante :

SBMJOB CMD(QSH CMD('export JAVA_HOME=<java-home>; exec bash *instanaAgentDir*/bin/start')) JOBQ(QUSRNOMAX) LOG(*JOBD *JOBD *NOLIST)
 

Cette commande lance les tâches de l'agent Instana dans le QUSRWRK sous-système et les exécute sous l'identité de l'utilisateur actuel. L'agent doit fonctionner en tant qu'utilisateur ayant l'autorité *ALLOBJ. Pour plus d'informations, consultez SBMJOB.

Une fois l'initialisation terminée, trois tâches distinctes nommées QZSHSH restent à exécuter pour faire fonctionner l'agent. Dans ces trois emplois, l'emploi qui possède la fonction PGM-sh est l'emploi parent. Le travail qui a la fonction PGM-jFromPASE est l'enfant direct du travail parent. L'emploi qui a la fonction JVM-org.apache est l'enfant du premier emploi enfant. D'autres tâches peuvent démarrer ou s'arrêter brièvement, en particulier pendant le démarrage.

Pour arrêter l'agent hôte, exécutez la commande suivante :

*instanaAgentDir*/bin/stop
 

Problème :

L'agent hôte ne parvient pas à se connecter à JVM.

Dans l'exemple de message d'erreur suivant, l'agent a tenté de se connecter au processus « JVM » (PID 123), mais l'opération a échoué :

2025-08-22T09:45:24.832-03:00 | INFO  | instana-executor-thread-2-98     | AttachHelperImpl | com.instana.agent-jvm-handling - 1.0.22 | Agent user {Uid=128, Gid=0} and target JVM user {Uid=4294770318, Gid=201} not identical.
2025-08-22T09:45:24.833-03:00 | INFO  | instana-executor-thread-2-98     | ExternalAttach   | com.instana.agent-jvm-handling - 1.0.22 | Executing: /opt/instana/instana-agent/system/com/instana/ibmi-sudo/1.0.0/ibmi-sudo-1.0.0.exe -u qwebadmin /QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit/jre/bin/java -Xms16m -Xmx16m -Dcom.ibm.tools.attach.enable=no -Duser.dir=/ -cp /tmp/.instana/javaagent-loader-1.3.70.jar com.instana.agent.loader.AgentLoaderAttach agent=/tmp/.instana/javaagent-loader-1.3.70.jar verify=true pid=123 host=127.0.0.1 port=42699 boot=/com.instana.agent.artifact/com.instana/instrumentation-boot/1.1.31/jar shared=/com.instana.agent.artifact/com.instana/instrumentation-shared/1.0.146/jar inMemoryClassLoader=true agentSocket=true
2025-08-22T09:45:25.301-03:00 | ERROR | instana-executor-thread-2-98     | ExternalAttach   | com.instana.agent-jvm-handling - 1.0.22 | com.sun.tools.attach.AttachNotSupportedException: target 123 not found
...
 

Cause :

Cette target <pid> not found erreur peut être due aux problèmes sous-jacents suivants :

• Le processus JVM ne s'exécute plus (ou a un nouveau PID).
• L'agent « Instana » ne dispose pas des autorisations nécessaires pour passer au profil utilisateur de l'« JVM ».

Solution :

Pour résoudre ce problème, procédez comme suit :

1. Vérifiez que l' JVM ion associée au PID est toujours en cours d'exécution en suivant les étapes suivantes :

   1. Exécutez la ps -e commande à partir d'un shell PASE.
   2. Recherchez le PID indiqué dans le message d'erreur, par exemple, 123.

   Si le processus associé à ce PID n'est plus en cours d'exécution, cela signifie que la connexion a échoué parce que l' JVM e s'est arrêté ou s'exécute désormais sous un nouveau PID. Dans ce cas, l'agent tente de s'associer au nouveau processus.

2. Si le service « JVM » est en cours d'exécution, vérifiez les droits de l'utilisateur. Le profil utilisateur de l'agent « Instana » doit disposer de l'autorisation *ALLOBJ spéciale permettant de s'exécuter sous un autre profil utilisateur, ce qui est nécessaire pour se connecter aux JVM. Pour plus de détails, voir qsysetuid().

   Pour vérifier les droits d'accès de l'utilisateur, procédez comme suit :

   1. Exécutez la ibmi-sudo commande manuellement avec le profil utilisateur « Instana », comme indiqué dans l'exemple suivant, en utilisant le chemin d'accès à ibmi-sudo l'exécutable indiqué dans le message d'erreur :

      /opt/instana/instana-agent/system/com/instana/ibmi-sudo/1.0.0/ibmi-sudo-1.0.0.exe -u qwebadmin /QOpenSys/pkgs/bin/whoami
       

      Si la commande sudo aboutit, le résultat affiché est le nom du profil utilisateur, par exemple :

      QWEBADMIN
       

      Si la commande sudo échoue, cela peut être dû au profil de OWNER(*GRPPRF)l'utilisateur cible. Si le premier groupe du profil utilisateur cible ne figure pas dans la liste des groupes supplémentaires de l'utilisateur de l'agent d' Instana, ajoutez le groupe cible à ces groupes supplémentaires.

   2. Ajoutez le groupe de l'utilisateur cible à la liste des groupes supplémentaires du profil utilisateur « Instana », comme indiqué dans l'exemple suivant :

      CHGUSRPRF USRPRF(INSTANA) SUPGRPPRF(TARGET_GROUP)
       

Si cette section consacrée au dépannage ne permet pas de résoudre vos problèmes, veuillez contacter l'équipe d'assistance d' IBM Instana.