Installing the host agent on IBM i (public preview)

Prerequisites

Ensure that the following prerequisites are met:

• Make sure that you install the following licensed programs in your system:

  • 5770-SS1 option 30, QSHELL
  • 5770-SS1 option 33, PASE
  • 5770-JV1, IBM Developer Kit for Java

  Option 17 for Java 8, option 19 for Java 11, or option 20 for Java 17

• Install some open source packages in IBM Portable Application Solutions Environment (PASE) for i. For more information about open source packages on IBM i, see RPM pile for IBM i releases in standard support. You can use the Open Source Package Management in IBM i Access Client Solutions (ACS) to install these packages in PASE. The necessary packages are installed by default. In addition to these packages, you must also install Bash and Tar-GNU (to extract the agent archive).

Supported sensors

The Instana host agent for IBM i is currently in public preview and is not tested on every sensor.

Check whether the local monitoring of IBM i can meet your goal by viewing the following list of supported sensors, which can be automatically discovered on IBM i. If not, use the remote monitoring of IBM i. For more information, see Monitoring IBM i instances.

• IBM i
• DB2 for IBM i
• Java virtual machine
• OS Process
• WebSphere Application Server
• WebSphere Liberty

Enabling JMX for WebSphere Liberty Metrics

To collect the metrics for WebSphere Liberty, you must enable the monitor-1.0 feature. To enable this feature, open the server.xml file, which is located in the <websphere-liberty_install_dir>/usr/servers/<specific_server>/ directory, and then add the following lines to the file:

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

Installing the agent manually

To install the host agent on IBM i, complete the following steps:

1. Download the agent archive to your local system:

   1. From the navigation bar of the Instana UI, click More > Agents > Install Agents.

   2. On the agent deployment catalog page, click the tile IBM i - Archive (tar.gz).

   3. Select the agent packaging mode, Dynamic or Static. For more information about dynamic and static host agents, see host agent types .

   4. Click the download link for IBM i to download the tar.gz file.

2. Create a target IFS directory (for example, /opt/instana/) on the IBM i system by running the following command:

   MKDIR DIR('/opt/instana')
   

3. Move the agent archive into the directory that you created in step 2. You can use FTP or the IFS interface of ACS to move the agent archive.

4. Extract the agent archive on the IBM i system by running the following commands:

   CALL QP2TERM
   

   cd <instana-directory>
   

   tar -xzf instana-agent-ibmi-ppc.tar.gz
   

   After you extract the agent archive, a new directory <instana-directory>/instana-agent is created. For example, /opt/instana/instana-agent.

5. Configure the agent to point to your Instana backend by using the <instana-agent-dir>/etc/instana/com.instana.agent.main.sender.Backend.cfg file. This file contains the configurations that are used by the host agent to communicate with the Instana backend, including the host and key. For more information, see Configuring the Instana Backend.

The host agent is now installed and configured on your IBM i system.

After you install the host agent, you can administer the host agent, such as checking the status of the agent or starting the agent.

You can also configure the agent as you require. For more information, see Configuring the host agent.

Installing the agent by using Ansible

You can use Ansible to automate the installation of the host agent on multiple IBM i nodes by using the following playbook. You can run this playbook on a UNIX-like server where Ansible is installed in it. This playbook automatically creates the destination directory, copies and extracts the agent archive, and starts the agent on all your IBM i systems.

For more information about the prerequisites and management of IBM i systems with Ansible, see Power IBM i collection for Ansible. For more IBM i examples, see Automate your IBM i tasks with Ansible.

To automate the installation of the host agent by using Ansible, complete the following steps:

1. Save the following playbook configuration as a YAML file, such as playbook.yml, in a directory of your system.

   ---
   - 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
       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'))
   

2. Download the agent archive by following step 1 in the Installing the agent manually section, and save it in the same directory as the playbook.

3. Create an inventory.ini file, which lists all the IBM i nodes where you want to install the agent, and save it in the same directory as the playbook. For more information about the inventory.ini file, see Build your inventory.

4. Run the playbook from your Ansible server by using the following command:

   ansible-playbook -i inventory.ini playbook.yml
   

The agent is deployed on all your IBM i systems that are specified in the inventory.ini file.

After you install the agent, you can further configure the agent as you require. Configurations can be applied when the agent runs, and changes are immediately applied. For more information, see Configuring the host agent.

Checking the status of the host agent

After you install the host agent, you can check the status of the agent in the Instana UI. For more information, see Checking the status of the host agent.

Starting the host agent

To start the host agent, run the following command:

SBMJOB CMD(QSH CMD('export JAVA_HOME=<java-home>; exec bash <instana-agent-dir>/bin/start')) JOBQ(QUSRNOMAX)

This command starts the Instana agent jobs in the QUSRWRK subsystem and runs the jobs as the current user. The agent needs to run as a user with *ALLOBJ authority. For more information, see SBMJOB.

After the initialization is complete, three separate jobs that are named QZSHSH remain to run the agent. In these three jobs, the job that has the function PGM-sh is the parent job. The job that has the function PGM-jFromPASE is the direct child of the parent job. The job that has the function JVM-org.apache is the child of the first child job. Other jobs might briefly start or stop, especially during the startup.

Stopping the host agent

To stop the host agent, run the following command:

<instana-agent-dir>/bin/stop