Integrating with IBM ITM V6

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.

Activating IBM ITM V6 support

To activate this support, you will need to do the following:

1. 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.
2. Enable the ibm-apmproxy sensor in your Instana host agent.
3. 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:

1. 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.
2. Enable the ibm-apmproxy sensor in your Instana host agent.
3. 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:

1. 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.
2. 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).

Configuration

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:

1. The support for IBM DataPower metrics through this integration requires the Instana server to be Build 201 or later.
2. The support for IBM ACE (IIB) metrics through this integration requires the Instana server to be Build 216 or later.
3. 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.
4. 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.
5. 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.
6. 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