IBM i へのホストエージェントのインストール

以下の前提条件が満たされていることを確認してください。

• IBM i 7.4 またはそれ以降

• 以下のライセンスプログラムがシステムにインストールされていることを確認してください：

  • 5770-SS1オプション30、QSHELL
  • 5770-SS1 オプション33、PASE
  • 5770-JV1、 IBM Developer Kit for Java ： Java 8の場合はオプション17、 Java 11の場合はオプション19（ IBM i 7.5 以前のバージョン）を選択してください。

• いくつかのオープンソースパッケージを IBM Portable Application Solutions Environment (PASE) for i にインストールします。 IBM i 上のオープン ソース パッケージについての詳細は、RPM pile for IBM i release in standard support を参照してください。 IBM i Access Client Solutions （ACS）のオープンソースパッケージ管理機能を使用して、PASEにこれらのパッケージをインストールできます。 必要なパッケージはデフォルトでインストールされる。 また、以下のパッケージもインストールする必要があります：

  • Bash
  • Tar-GNU（エージェントアーカイブを展開するため）。

以下のリストは、サポートされているセンサーの一部に過ぎませんが、これらを確認することで、 IBM i によるローカル監視が目的を満たすかどうかを確認できます。これらのセンサーは、 IBM i で自動的に検出されます。 そうでない場合は、IBM i のリモート監視を使用してください。 詳細については、 「 IBM i インスタンスの監視」 を参照してください。

• Apache Tomcat
• 自動化アクションスクリプト
• Db2 for IBM i
• IBM i
• IBM MQ
• Java 仮想マシン
• Node.js
• Python
• Spring Boot
• WebSphere Application Server
• WebSphere Liberty

WebSphere Liberty のメトリックを収集するには、monitor-1.0 機能を有効にする必要があります。 この機能を有効にするには、<websphere-liberty_install_dir>/usr/servers/<specific_server>/ディレクトリにあるserver.xmlファイルを開き、次の行をファイルに追加します：

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

IBM i 7.6 ユーザープロファイルに対して多要素認証（MFA）を導入します。 Instana エージェントは、MFAが有効になっているかどうかにかかわらず、ユーザープロファイルで実行できます。 詳細については、 「ホストエージェントの起動」 を参照してください。

Java ベースのテクノロジーを監視するには、 Java ジョブがエージェントとは異なるユーザーによって実行されている場合、 Instana エージェントは、そのジョブを実行しているユーザーのプロファイルに切り替える必要があります。 一般的に、 Instana エージェントは、そのユーザープロファイルのTOTPがなくても、MFAが有効になっているユーザープロファイルに切り替えることができます。 ただし、エージェントは、その QIBM_RUN_UNDER_USER_NO_AUTH 機能使用IDへのアクセスが拒否されているユーザープロファイルに切り替えることはできません。 デフォルトでは、すべてのユーザープロファイル（MFAの有無にかかわらず）がこの機能使用IDへのアクセスが許可されており、これにより Instana エージェントがそれらのJVMに接続できるようになります。 詳細については、 QIBM_RUN_UNDER_USER_NO_AUTH 関数の使用方法 ID を参照してください。

MFA を使用した「 IBM i 」のリモート監視に関する詳細については、 「MFA に関する注意事項」 を参照してください。

IBM i にホストエージェントをインストールするには、以下の手順を実行します：

1. エージェントアーカイブをローカルシステムにダウンロードする：

   1. Instana UIのナビゲーションバーから、 「その他 」>「 エージェント 」>「 エージェントのインストール」 をクリックします。

   2. エージェント展開カタログページで、タイル IBM i - Archive (tar.gz) をクリックします。

   3. エージェントのパッケージングモード、DynamicまたはStaticを選択します。 動的ホストエージェントおよび静的ホストエージェントの詳細については、 「ホストエージェントの種類」 を参照してください。

   4. IBM i のダウンロード・リンクをクリックして、tar.gz ファイルをダウンロードしてください。

2. 以下のコマンドを実行して、IBM iシステム上にターゲットIFSディレクトリ（たとえば、/opt/instana/）を作成します：

   MKDIR DIR('/opt/instana')
    

3. エージェントアーカイブを手順2で作成したディレクトリに移動します。 エージェントアーカイブを移動するには、FTP または ACS の IFS インタフェースを使用します。

4. 以下のコマンドを実行して、IBM i システム上のエージェント・アーカイブを展開します：

   CALL QP2TERM
    

   cd <instana-directory>
    

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

   エージェントアーカイブを展開すると、新しいディレクトリ <instana-directory>/instana-agent が作成されます。 例えば、/opt/instana/instana-agentです。

5. ファイル *instanaAgentDir*/etc/instana/com.instana.agent.main.sender.Backend.cfg を使用して、エージェントが Instana のバックエンドを指すように設定します。 このファイルには、ホストエージェントが Instana バックエンドと通信するために使用する設定が含まれています。これには、 host およびが含まれます key。 詳細については、 「 Instana バックエンドの設定」 を参照してください。

これで、IBM i システムにホスト・エージェントがインストールされ、構成されました。

ホストエージェントをインストールした後、エージェントの状態を確認したり、エージェントを起動したりといったホストエージェントの管理を行うことができます。

また、必要に応じてエージェントを設定することもできます。 詳細については、 「ホストエージェントの設定」 を参照してください。

Ansible を使用して、以下の playbook を使用することで、複数の IBM i ノードへのホスト・エージェントのインストールを自動化できます。 このプレイブックは、 Ansible がインストールされているUNIX系サーバー上で実行できます。 このプレイブックは、インストール先ディレクトリを自動的に作成し、エージェントアーカイブをコピーして抽出し、すべてのIBM i システム上でエージェントを起動します。

IBM i システムの Ansible での前提条件と管理の詳細については、Power IBM i collection for Ansible を参照してください。 IBM i のその他の使用例については、 「 Ansible を使用して IBM i のタスクを自動化する 」をご覧ください。

Ansible を使用してホストエージェントのインストールを自動化するには、以下の手順を実行します：

1. 以下のプレイブック設定を、システムの任意のディレクトリに、 YAML ファイル（例： playbook.yml）として保存してください。

   ---
   - 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. エージェントを手動でインストールするセクションのステップ1に従ってエージェントのアーカイブをダウンロードし、playbookと同じディレクトリに保存します。

3. エージェントをインストールしたいすべてのIBM iノードをリストしたinventory.iniファイルを作成し、playbookと同じディレクトリに保存します。 この inventory.ini ファイルの詳細については、 「インベントリの作成」 を参照してください。

4. 以下のコマンドを使用して、Ansibleサーバーからplaybookを実行します：

   ansible-playbook -i inventory.ini playbook.yml
    

エージェントは、inventory.iniファイルで指定されたすべてのIBM iシステムに展開されます。

エージェントをインストールした後、必要に応じてエージェントをさらに設定することができます。 設定はエージェントの実行時に適用することができ、変更は直ちに適用されます。 詳細については、 「ホストエージェントの設定」 を参照してください。

ホストエージェントのインストールが完了したら、 Instana のUIでエージェントのステータスを確認できます。 詳細については、ホストエージェントの状態を確認するを参照してください。

ホスト・エージェントを起動するには、以下のコマンドを実行する：

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

このコマンドは、サブシステム QUSRWRK 内の Instana エージェントジョブを起動し、現在のユーザーとしてジョブを実行します。 エージェントは*ALLOBJの権限を持つユーザーとして実行する必要があります。 詳細については、 SBMJOB を参照してください。

初期化が完了すると、エージェントを実行するためにQZSHSHという名前の3つの別々のジョブが残ります。 これらの3つのジョブでは、PGM-shという関数を持つジョブが親ジョブです。 PGM-jFromPASEという関数を持つジョブは、親ジョブの直接の子ジョブです。 JVM-org.apacheという関数を持つジョブは、最初の子ジョブの子です。 他のジョブは、特にスタートアップ中に、短時間起動したり停止したりすることがある。

ホスト・エージェントを停止するには、以下のコマンドを実行する：

*instanaAgentDir*/bin/stop
 

問題点 ：

ホストエージェントが JVM に接続できませんでした。

次のエラーメッセージの例では、エージェントが JVM （PID 123）に接続しようとしましたが、失敗しました：

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
...
 

原因 ：

この target <pid> not found エラーは、以下の根本的な原因によって引き起こされる可能性があります：

• JVM プロセスは実行されていません（または新しいPIDが割り当てられています）。
• Instana エージェントには、 JVM のユーザープロファイルに切り替える権限がありません。

解決策 ：

この問題を解決するには、以下のステップを実行します。

1. 以下の手順に従って、PID を持つ JVM がまだ実行中であることを確認してください：

   1. PASEシェルからこの ps -e コマンドを実行してください。
   2. エラーメッセージに記載されているPIDを検索してください。例えば、 123.

   そのPIDを持つプロセスが実行されていない場合、 JVM が停止したか、新しいPIDで実行されているため、接続に失敗しました。 この場合、エージェントは新しいプロセスにアタッチしようとします。

2. JVM が実行中の場合は、ユーザーの権限を確認してください。 Instana エージェントのユーザープロファイルには、別のユーザープロファイルとして実行するための特別な *ALLOBJ 権限が必要です。これは、JVMに接続するために必須の要件です。 詳細については、 qsysetuid() を参照してください。

   ユーザーの権限を確認するには、以下の手順を実行してください：

   1. エラーメッセージに記載されている実行 ibmi-sudo ファイルのパスを使用して、以下の例に示すように、 Instanaibmi-sudo ユーザープロファイルでコマンドを手動で実行してください：

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

      sudo コマンドが正常に実行されると、ユーザープロファイルの名前が表示されます。例えば：

      QWEBADMIN
       

      sudo コマンドが失敗した場合、対象のユーザープロファイルに指定されている可能性があります OWNER(*GRPPRF)。 対象ユーザープロファイルの最初のグループが、 Instana エージェントユーザーの補助グループ一覧に含まれていない場合は、そのグループを補助グループに追加してください。

   2. 次の例に示すように、対象ユーザーのグループを「 Instana 」ユーザープロファイルの補助グループ一覧に追加します

      CHGUSRPRF USRPRF(INSTANA) SUPGRPPRF(TARGET_GROUP)
       

このトラブルシューティングの手順で問題が解決しない場合は、 IBM （ Instana ）のサポートチームまでお問い合わせください。