Integrating with IBM ITM V6
- Summary
- Activating IBM ITM V6 support
- Activating IBM APM V8 support
- Supported Versions
- Configuration
- Metrics collection
- Known Issues
- Health Signatures
- Additional Information
Summary
The Integration of IBM Tivoli Monitoring V6 with Instana is accomplished by updating the ITM V6 or ITCAM V7 agents to communicate in dual mode. This allows the agents to continue to send data to the IBM TEMS server as well as the new IBM Monitoring Instana Integration Service. The IBM Monitoring Instana Integration Service receives and transforms the metric payloads from the agents and provides those payloads to the ibm-apmproxy sensor upon request. The ibm-apmproxy sensor in the Instana host agent sends the payloads to the Instana server where the payloads are processed, creating entities in the Instana server, and saving the metrics for display in the Instana UI. Beginning with IBM Monitoring Instana Integration Service 1.1.0, IBM Application Performance Monitoring (APM) V8 agents can also be integrated with an Instana server using this service. IBM APM V8 agents must be connected to only one monitoring server, APM v8 or the IBM Monitoring Instana Integration Service. Beginning with IBM Monitoring Instana Integration Service 1.1.1, IBM APM V8 MQ and ACE (IIB) agents as well as ITCAM V7 MQ and IIB agents can be integrated with an Instana server. Beginning with IBM Monitoring Instana Integration Service 1.1.3, IBM APM V8 WAS agents and ITCAM V7 WAS agents can be integrated with an Instana server.
Upgrade Considerations
If you have previously installed the IBM Monitoring Instana Integration Service on OpenShift Container Platform and are upgrading to version 1.1.0, be aware of the following changes: In prior releases, only HTTP was supported for ingress on Red Hat OpenShift. Beginning with release 1.1.1, HTTPS is the only supported protocol for all platforms, including Red Hat OpenShift. The support for the HTTP protocol is removed.
If HTTP was used to configure the Instana OS agent IBM APM-Proxy sensor in a prior deployment of the service, the protocol must be changed to HTTPS and the port must be set to 443.
Activating IBM ITM V6 support
To activate this support, you will need to do the following:
- Download the deployment package for the IBM Monitoring Instana Integration Service from https://github.com/instana/ibm-monitoring-integration and follow the instructions to deploy the service. If you have previously deployed this service, deploying it again using the new deployment package will cause it to be upgraded.
- Enable the ibm-apmproxy sensor in your Instana host agent.
- Configure the supported ITM V6 or ITCAM V7 agents to communicate with the IBM Monitoring Instana Integration Service.
The deployment package provides the ability to deploy the IBM Monitoring Instana Integration Service on a system that does not have a connection to the internet (aka "air-gapped").
The deployment supports High Availability (HA) mode for new deployments. When HA mode is enabled, three pod instances are created for statefulset components (zookeeper and kafka). For stateless components, the number of replicas can be specified (the minimum number of replicas is 2).
Metric ingestion via the ibm-apmproxy sensor in the host agent is deactivated by default. To enable the reception of ITM agent data in the host agent, refer to the Sensor configuration section. Note that the ITM V6 support reuses the ibm-apmproxy sensor that was originally provided for integration with IBM APM V8.
Activating IBM APM V8 support
APM V8 agents connected to the IBM Monitoring Instana Integration Service can only display metrics in the Instana UI and cannot send metrics to the APM V8 server. If you need the ability to see the metrics from the APM V8 agents in both the APM V8 UI and the Instana UI, refer to the "server to server" support for APM V8 documented in ibm-apmproxy sensor documentation
If you have not already deployed the IBM Monitoring Instana Integration Service, you will need to do the following:
- Download the deployment package from the IBM Monitoring Instana Integration Service from https://github.com/instana/ibm-monitoring-integration and follow the instructions to deploy the service.
- Enable the ibm-apmproxy sensor in your Instana host agent.
- Configure the supported APM V8 agents to communicate with the IBM Monitoring Instana Integration Service.
If you have already deployed the IBM Monitoring Instana Integration Service for use with ITM V6 and ITCAM V7 agents, you will need to do the following:
- Download the deployment package for the IBM Monitoring Instana Integration Service from https://github.com/instana/ibm-monitoring-integration and locate the documentation for configuring agents.
- Configure the supported APM V8 agents to communicate with the IBM Monitoring Instana Integration Service.
Supported Versions
The IBM Monitoring Instana Integration service has generally available support for metrics from the following ITM, ITCAM and APM V8 agents:
- Linux OS agent Version 6.3.0.7 SP 6 or later on xLinux, zLinux, and pLinux
- IBM APM V8 Linux OS agent Version 06.35.14.0.21 or later on xLinux, zLinux, and pLinux
- Datapower agent Version 7.1.1 FP3 or later
- IBM APM V8 Datapower agent 8.20.06 or later
- Windows OS agent Version 6.3.0.7 SP 6 or later
- IBM APM V8 Windows OS agent Version 06.35.14.17 or later
- Unix OS agent Version 6.3.0.7 SP 6 or later on AIX
- IBM APM V8 Unix OS agent 06.35.14.17 or later on AIX
- IBM MQ agent Version 7.3 FP3 or later
- IBM ACE(IIB) agent Version 7.3 FP3 or later
- IBM APM V8 MQ agent Version 8.20.04 or later
- IBM APM V8 ACE agent Version 8.20.04 or later
- IBM WAS agent Version 7.2 IF12 or later
- IBM WAS V8 agent Version 8.20.04 or later
ITM and ITCAM agents must be patched to 6.3.0.7 IF0009 of the TEMA (core framework). APM V8 agents must be patched to 8.1.4.0 IF0018 of the TEMA (core framework).
Platforms and Prerequisites
The prerequisites for the IBM Monitoring Instana Integration Service are:
- Kubernetes cluster running on Intel 64 bit (amd64) Linux OS.
- Supported Kubernetes versions: 1.19, 1.20, 1.21, 1.22, 1.23
- Note that support for Kubernetes 1.22 and 1.23 require version 1.1.0 or later of the IBM Monitoring Instana Integration Service.
- At least 8 CPU cores and 16 GB of memory that can be allocated to the IBM Monitoring Instana Integration Service.
- An ingress controller (such as nginx) that is configured to enable external network access to the cluster.
- A default persistent storage class that has 30 GB available.
The tested and supported platforms for the IBM Monitoring Instana Integration Service are:
- MicroK8s 1.21/stable, 1.22/stable, 1.23/stable, and 1.24/stable (https://microk8s.io/)
- Red Hat OpenShift Container Platform 4.6.52
- Red Hat OpenShift Container Platform 4.8.27
- Red Hat OpenShift Container Platform 4.9.13
- Red Hat OpenShift Container Platform 4.10.13
For all of the OpenShift Container Platform versions, see the section [Apm Proxy Performance Considerations](# Apm-Proxy-Performance-Considerations)
The ITM V6 and ITCAM V7 agents must be patched to use a level of the core framework (TEMA) that supports dual path communications. Obtain and apply the 6.3.0.7-TIV-ITM_TEMA-IF0009 patch (or a later version) to the agents that you want to connect. The APM V8 agent must be patched to use a level of the core framework (TEMA) that supports connection to a server other than APM V8. Obtain and apply the 8.1.4.0-IBM-APM-CORE-FRAMEWORK IF0018 patch (or a later version) to the agents that you want to connect.
Configuration
Dependencies
In order for the sensor to gather metrics from the ITM V6, ITCAM V7 or APM V8 agents, the IBM Monitoring Instana Integration Service needs to be installed. Begin by downloading the deployment package from http://github.com/instana/ibm-monitoring-integration
The deployment package includes documentation and additional instructions. Please refer to the "readme.txt" file in the deployment package for further details.
Before you attempt to deploy the IBM Monitoring Instana Integration Service, have your Instana agent key available, since the deployment script will prompt for this information.
IBM Agent configuration
Refer to the documentation in the deployment package for information about configuring the IBM agents (ITM, ITCAM or APM) to communicate with the IBM Monitoring Instana Integration Service. A script is provided that will obtain the correct configuration package so that you can apply it to your agent and reconfigure its communication.
Sensor configuration
To enable the ibm-apmproxy sensor, locate the ibmapmproxy section of the agent configuration file and uncomment the lines for the sensor. Provide the host, protocol and port information for the IBM ITM Instana Integration Service that you
installed in the previous steps in the corresponding fields:
<agent_install_dir>/etc/instana/configuration.yaml
:
com.instana.plugin.ibmapmproxy:
enabled: true
# host: Provide the hostname or IP address of the system where the IBM Monitoring Instana Integration Service is running. No quotation marks are needed.
host: '<INSERT_HOST_HERE>' # Instana Integration Component host
# port: provide the port defined for contacting the IBM Monitoring Instana Integration Service. No quotation marks are needed.
port: 443 # Instana Integration Component port Default
datainterval: 1 # Default
heartbeatinterval: 15 # Default
# protocol: indicate whether to connect with the IBM Monitoring Instana Integration Service using the secure (SSL) port or the insecure port. Values are either "http" or "https". Default is "https". No quotation marks are needed. Ensure the value provided for the "port" variable is the appropriate port for your server.
protocol: https # Default
Metrics collection
To view the metrics, select Infrastructure in the sidebar of the Instana User interface, click a specific monitored host, and then you can see a host dashboard with all the collected metrics and monitored processes.
Only metrics are collected using this integration. No traces from ITCAM agents are collected through this path.
See the Instana Host sensor for the list of collected metrics from the Linux OS agent, the Windows OS agent and the Unix OS agent. See the IBM Datapower sensor for the list of collected metrics from the IBM Datapower agent. See the IBM MQ sensor for the list of collected metrics from the IBM MQ agent. See the IBM ACE sensor for the list of collected metrics from the IBM ACE(IIB) agent. See the IBM WAS sensor for the list of collected metrics from the IBM WebSphere Application Server (WAS) agent.
Notes:
- The support for IBM DataPower metrics through this integration requires the Instana server to be Build 201 or later.
- The support for IBM ACE (IIB) metrics through this integration requires the Instana server to be Build 216 or later.
- To provide support for IBM WAS metrics through this integration, an IBM OS agent needs to be installed and running on the same system as the IBM WAS agent.
- Several metrics expected in the Instana Host, Datapower-related, MQ-related, ACE(IIB)-related and WAS-related entities are not currently collected by the IBM agents. These metrics will be blank or null in the Instana UI. A PDF document named
InstanaVisualizationOfITMAgents.pdf
is provided with the deployment package to help in mapping the metrics on the Instana UI to the ITM Tivoli Enterprise Portal (TEP) UI. - Metrics are collected from the supported IBM monitoring agents, which are attached to the IBM Monitoring Instana Integration Service and forwarded to Instana, and then Host, Datapower, MQ, ACE (IIB) and WAS entities are created on the Instana UI.
- Metrics are collected by the IBM monitoring agents at the interval defined in the subscription files that are provided to the agents from the IBM Monitoring Instana Integration Service. The available metrics from all supported agents are retrieved by the apmproxy sensor every one second when these metrics become available at the IBM Monitoring Instana Integration Service.
Known Issues
When you check the metrics in the Instana UI for a host entity that are created by the IBM Monitoring Instana Integration service, you might find that the Open Agent Management button in the Instana UI does not work. This is
expected and normal because the metrics are not provided by the Instana agent, which is running directly on the monitored host.
If you need to check the operation of the Instana agent in this scenario, select Agents in
the side navigation, and locate the Instana agent that are running on the same host as the IBM Monitoring Integration service.
Health Signatures
Refer to the ibm-apmproxy sensor documentation for the Health Signature information.
Additional Information
Apm Proxy Performance Considerations
For the Instana integration service running in an OpenShift cluster, if there will be an Instana agent monitoring the cluster, we recommend that the agent be configured in Infrastructure mode rather than APM mode.