Integrating with IBM ITM V6 (public preview)

Summary

The integration of IBM Tivoli Monitoring V6 with Instana is accomplished by using the ITM sensor for the Instana host agent. ITM V6 or ITCAM V7 agents are configured to communicate in dual mode, which allows them to continue sending data to the IBM TEMS server while also sending data to the Instana host agent. The ITM sensor in the Instana host agent receives the metric payloads from the ITM agents and sends them to the Instana backend where the payloads are processed, creating entities in the Instana server and saving the metrics for display in the Instana UI.

Prerequisites

Before you begin, ensure that you have the following:

• An Instana host agent installed directly on a host operating system. The agent must be installed on the host OS itself, not as a container or in a Kubernetes/OpenShift environment. For more information, see Installing the host agent.
• ITM V6 and ITCAM V7 agents patched with the required TEMA (core framework) patches:
  • To connect over HTTP: Apply 6.3.0.7-TIV-ITM_TEMA-IF0003 or later patch.
  • To connect over HTTPS: Apply 6.3.0.7-TIV-ITM_TEMA-IF0008 or later patch.

Activating ITM support

To activate ITM V6 support, you must complete the following steps:

1. Enable the ITM sensor in your Instana host agent.
2. Download and configure the ITM agent configuration pack.
3. Configure your ITM V6 agents to connect to the Instana host agent.

Enabling the ITM sensor

Metric ingestion by using the ITM sensor in the host agent is deactivated by default. To enable the ITM sensor, locate the com.instana.plugin.itm section of the agent configuration file and configure the sensor.

Edit <agent_install_dir>/etc/instana/configuration.yaml:

# ITM Sensor
com.instana.plugin.itm:
  enabled: true
#  availabilityZone: 'My ITM zone' # default is 'ITM Remote Monitoring'

Configuration options:

• enabled: Set to true to activate the ITM sensor.
• availabilityZone: Optional custom name for grouping ITM entities in Instana. If not specified, defaults to ITM Remote Monitoring.

Adjusting storage requirements

To adjust storage requirements for the Instana host agent when using the ITM sensor, modify the following file: /opt/instana/agent/bin/setenv.

Then, modify the following lines with the updated values as shown in the following example:

DEFAULT_AGENT_MAX_MEM='2048m'
DEFAULT_HEAP_MAX_MEM='320m'

Configuring TLS or HTTPS communication

By default, ITM agents communicate with the Instana host agent over HTTP on port 42699. For secure communication, you can configure TLS/HTTPS connections between ITM agents and the Instana host agent.

Setting up HTTPS requires:

1. Configuring TLS certificates on the Instana host agent to enable HTTPS on port 42699.
2. Creating IBM GSK (Global Security Kit) keyring files for ITM agents that trust the Instana host agent's certificate.
3. Updating the env.properties file to use protocol=https.

For instructions on configuring TLS/HTTPS, see Configuring TLS/HTTPS for ITM V6 Integration.

Configuration pack setup

To configure your ITM V6 agents to connect to the Instana host agent, you must download and use the agent configuration pack.

Downloading the configuration pack

1. Download the agent configuration pack from the latest release at https://github.com/instana/ibm-monitoring-integration/releases.
2. Download either the instana-v6-configpack.zip or instana-v6-configpack.tar file.
3. Extract the configuration pack to a temporary directory on the system where you will run the configuration.

Configuring ITM agents

You can configure ITM V6 agents either locally (on the same system where the agents are installed) or remotely (using tacmd commands).

Local configuration

To locally configure the V6 agents to connect to the Instana host agent, complete the following steps on the system where the V6 agents are installed:

1. Edit the env.properties file in the extracted configuration pack and replace INSTANA_AGENT_HOST with the hostname where your Instana host agent is running. For example:

   hostname=instana.example.com

   Note:

   To use HTTPS instead of HTTP, see Configuring TLS/HTTPS for ITM V6 Integration for complete setup instructions.
2. Run the agent2server_itm script with the -i, -c, and -e options:

   AIX/Linux:

   ./agent2server_itm.sh -i <agent_install_dir> -c <connection_mode> -e env.properties

   Windows:

   agent2server_itm.bat -i <agent_install_dir> -c <connection_mode> -e env.properties

   Where:

   • <agent_install_dir> is the agent installation directory. For example, /opt/IBM/ITM.
   • <connection_mode> is either:
     • dual - Agent connects to both TEMS and Instana host agent.
     • instana - Agent connects only to Instana host agent.
   Note:

   On Linux or AIX systems, the default system shell linked to /bin/sh must be sh, bash, or ksh.
   Note:

   Any agents currently running are restarted by the script.

Remote configuration

To remotely configure the V6 agents to connect to the Instana host agent, complete the following steps:

1. Edit the env.properties file in the extracted configuration pack and replace INSTANA_AGENT_HOST with the hostname where your Instana host agent is running. For example:

   hostname=instana.example.com

   Note:

   To use HTTPS instead of HTTP, see Configuring TLS/HTTPS for ITM V6 Integration for complete setup instructions.
2. Create a temporary directory on the remote system where the V6 agent is installed:

   Linux example:

   tacmd executecommand -m kvm-011235:LZ -c "nohup /bin/sh -c 'mkdir /tmp/configpack > /tmp/output'"

   Windows example:

   tacmd executecommand -m Primary:IMG-WINDOWS2008:NT -c "md C:\IBM\ITM\configpack"

3. Transfer the agent configuration pack files to the remote system:

   Linux example (extracted files):

   tacmd putfile -m kvm-011235:LZ -s /mnt/configpacks/instana-v6-configpack/agent2server_itm.sh -d /tmp/configpack/agent2server_itm.sh -t text
   tacmd putfile -m kvm-011235:LZ -s /mnt/configpacks/instana-v6-configpack/env.properties -d /tmp/configpack/env.properties -t text
   # Make the script executable
   tacmd executecommand -m kvm-011235:LZ -c "chmod +x /tmp/configpack/agent2server_itm.sh"

   Windows example (extracted files):

   tacmd putfile -m Primary:IMG-WINDOWS2008:NT -s C:\temp\instana-v6-configpack\agent2server_itm.bat -d C:\IBM\ITM\configpack\agent2server_itm.bat -t text
   tacmd putfile -m Primary:IMG-WINDOWS2008:NT -s C:\temp\instana-v6-configpack\env.properties -d C:\IBM\ITM\configpack\env.properties -t text

4. Run the agent2server_itm script on the remote system:

   Linux example (dual mode):

   tacmd executecommand -m kvm-011235:LZ -c "nohup /bin/sh -c 'sleep 10; /tmp/configpack/agent2server_itm.sh -i /opt/IBM/ITM -c dual -e /tmp/configpack/env.properties > /tmp/output' &" -w /tmp/configpack

   Windows example (dual mode):

   tacmd executecommand -m Primary:IMG-WINDOWS2016:NT -c "START /B C:\IBM\ITM\configpack\agent2server_itm.bat -i C:\IBM\ITM -e C:\IBM\ITM\configpack\env.properties -c dual" -w C:\IBM\ITM\configpack

   Replace -c dual with -c instana if you want the agents to connect only to the Instana host agent.

   Note:

   The tacmd executecommand command returns immediately, but the script continues running in the background on the remote system. To check the results, wait a few moments and then view the output file:

   • Linux: tacmd executecommand -m kvm-011235:LZ -c "cat /tmp/output"
   • Windows: tacmd executecommand -m Primary:IMG-WINDOWS2016:NT -c "type C:\IBM\ITM\configpack\output.log"
   Note:

   On AIX or Linux systems, the sh, bash, or ksh shell is required to run the agent2server_itm script on the remote system.

Configuring custom agents (Agent Builder or Agent Factory)

If you have custom ITM agents built with Agent Builder or Agent Factory, you must include the SDA (Self Describing Agent) jar file to enable proper integration with Instana. Use the -j option to specify the location of the SDA jar file.

Syntax:

-j "productcode=path_to_support_directory"

Where:

• productcode is the 2-character ITM product code (for example, 01 for a custom agent).
• path_to_support_directory is the directory containing the SDA JAR file.

The support directory must contain a JAR file matching the pattern k{productcode}_sda_*.jar or {productcode}_sda_*.jar. For information about creating SDA-enabled custom agents, see ITM Agent Builder XML Configuration for SDA.

Local configuration examples:

AIX/Linux:

./agent2server_itm.sh -i /opt/IBM/ITM -c dual -j "01=/tmp/k01/support"

Windows:

agent2server_itm.bat -i C:\IBM\ITM -c dual -j "01=C:\Downloads\k01\support"

Multiple custom agents:

To configure multiple custom agents, separate the mappings with commas:

-j "01=/path/to/k01/support,11=/path/to/k11/support"

What the script does:

When you specify the -j option, the script:

• Validates that the SDA JAR file exists in the specified support directory.
• Copies the JAR file to the appropriate ITM agent support directory on the target system.
• Expects JAR file naming pattern: k{productcode}_sda_*.jar or {productcode}_sda_*.jar.

For example, for product code 01, the script looks for k01_sda_*.jar or 01_sda_*.jar in the specified directory.

Remote configuration with custom agents:

When using remote configuration with tacmd, you can include the -j option in the executecommand command:

Linux example:

tacmd executecommand -m kvm-011235:LZ -c "nohup /bin/sh -c 'sleep 10; /tmp/configpack/agent2server_itm.sh -i /opt/IBM/ITM -c dual -e /tmp/configpack/env.properties -j "01=/tmp/k01/support" > /tmp/output' &" -w /tmp/configpack

Windows example:

tacmd executecommand -m Primary:IMG-WINDOWS2016:NT -c "START /B C:\IBM\ITM\configpack\agent2server_itm.bat -i C:\IBM\ITM -e C:\IBM\ITM\configpack\env.properties -c dual -j "01=C:\temp\k01\support"" -w C:\IBM\ITM\configpack

Configuration result

After configuration, the ITM V6 agents will connect based on the mode you specified:

• Dual mode (-c dual): Agents connect to both TEMS and the Instana host agent. Monitoring data is available on both the TEP and the Instana user interface.
• Instana mode (-c instana): Agents connect only to the Instana host agent. Monitoring data is available only in the Instana user interface.

Reconnecting to TEMS only

If you need to reconnect the agents to TEMS only, run the following command:

AIX/Linux:

./agent2server_itm.sh -i <agent_install_dir> -c itm

Windows:

agent2server_itm.bat -i <agent_install_dir> -c itm

Where <agent_install_dir> is the agent installation directory.

Supported ITM agent versions

The ITM sensor supports ITM V6 agents version 6.3.0.7 or later that have been patched with the required TEMA (core framework) patches. See Prerequisites for specific patch requirements.

Data visualization

The way monitoring data is visualized in Instana depends on the type of ITM agent:

Native Instana entity types

The following ITM agent types are displayed using the built-in dashboards for native Instana entity types:

• Linux OS agent, Windows OS agent, Unix OS agent (AIX) - See the Host sensor for collected metrics.
• IBM MQ agent - See the IBM MQ sensor for collected metrics.

OpenTelemetry entity types

All other ITM agent types (such as DataPower, App Connect Enterprise (ACE), WebSphere Application Server (WAS), and custom agents built with Agent Builder/Agent Factory) are visualized as OpenTelemetry entities in Instana.

Custom agent SDA support

For custom agents built with Agent Builder/Agent Factory to provide SDA (Self Describing Agent) content to Instana, the SDA JAR file must be included in the agent build. For configuration details, see ITM Agent Builder XML Configuration for SDA.

Metrics collection

To view the metrics collected from ITM V6 agents, select Infrastructure in the sidebar of the Instana user interface, click a specific monitored host or entity, and then you can see a dashboard with all the collected metrics.

How metrics are collected

1. Subscription file management: The ITM sensor provides subscription files to ITM V6 agents when they request them. These files define which metrics to collect and the collection intervals (SUBINTERVAL values) for each table.
2. ITM agent data collection: ITM V6 agents collect metrics for tables based on the SUBINTERVAL values defined in their subscription files (typically 1-5 minutes). Each table can have a different collection interval.
3. Data transmission based on connection mode:
   • Dual mode (-c dual): After collection, ITM agents send metrics to both TEMS (for TEP display) and the Instana host agent (for Instana UI display).
   • Instana mode (-c instana): After collection, ITM agents send metrics only to the Instana host agent (for Instana UI display).
4. ITM sensor processing: The ITM sensor in the Instana host agent processes the data as it is received from the ITM agents and forwards it to the Instana backend.
5. Metric availability: The integration collects core performance metrics from ITM agents. Some specialized or historical metrics available in TEP might not be available in Instana, as the integration focuses on key performance metrics.

Troubleshooting

Connection issues

If ITM agents are not connecting to the Instana host agent:

1. Verify that the ITM sensor is enabled in the Instana host agent configuration.
2. Check that the env.properties file has the correct hostname for the Instana host agent.
3. Ensure that the ITM agents have been patched with the required TEMA framework patches.
4. Verify network connectivity:
   • Test connectivity: telnet <instana_host> 42699
   • Ensure port 42699 is open on the Instana host agent system.
   • Check firewall rules allow traffic from ITM agent systems.
5. Review logs:
   • ITM agent logs: $CANDLEHOME/logs/<hostname>_<product_code>_*.log.
   • Instana host agent logs: /opt/instana/agent/data/log/agent.log.

Failed to connect to the Instana host agent

If ITM agents cannot connect to the Instana host agent, you might need to configure the host agent to listen on the available network interfaces. For more information, see General Reference - Network.

The ITM agents send data to the Instana host agent on port 42699 (as defined in the env.properties file). Ensure this port is accessible from the systems where your ITM agents are running.

Missing metrics

If metrics are not appearing in Instana:

1. Verify that the ITM agents are running in dual mode.
2. Check that the Instana host agent is receiving data from the ITM sensor.
3. Review the Instana host agent logs for any errors related to the ITM sensor.
4. Ensure that the ITM agents are configured to collect the expected metrics.