Integrating with IBM ITM V6

Technology Preview Code

Note: The IBM Tivoli Monitoring V6 support in Instana is in technology preview, and we are hard at work to make the IBM ITM V6 integration a first-class citizen.

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

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
  2. Enable the ibm-apmproxy sensor in your Instana host agent
  3. Configure the ITM V6 or ITCAM V7 agents to communicate with the IBM Monitoring Instana Integration Service

Update: Version 0.0.2 of the deployment package now 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").

Metric ingestion via the ibm-apmproxy sensor in the host agent is deactivated by default. To enable the reception of IBM ITM V6 data in the host agent, please refer to the Sensor configuration section below. Note that the ITM V6 support reuses the ibm-apmproxy sensor that was originally provided for integration with IBM APM V8.

Supported Versions

This technology preview has support for metrics for IBM Tivoli Monitoring Version 6.3.0.7 SP6 or higher with the following ITM and ITCAM agents:

  • Linux OS agent Version 6.3.0.7 SP 6 or higher ; supported on xLinux,zLinux,pLinux
  • Datapower agent Version 7.1.1 FP3 or higher
  • Windows OS agent Version 6.3.0.7 SP 6 or higher
  • Unix OS agent Version 6.3.0.7 SP 6 or higher ; supported on AIX

Note: agents must be patched to 6.3.0.7 IF0009 of the TEMA (core framework)

Platforms and Pre-requisites

The prerequisites for the IBM Monitoring Instana Integration Service are:

  • Kubernetes cluster running on Intel 64 bit (amd64) Linux OS. (Note: Kubernetes 1.22 is not supported.)
  • 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 supported platforms for the IBM Monitoring Instana Integration Service during the technology preview are:

The ITM V6 agents must be patched to use a level of the core framework (TEMA) that supports dual path communications. Please obtain and apply the 6.3.0.7-TIV-ITM_TEMA-IF0009 patch (or a later version) to the agents you wish to test.

Configuration

Dependencies

In order for the sensor to gather metrics from the ITM V6 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, please have your Instana agent key available, since the deployment script will prompt for this information.

ITM V6 and ITCAM V7 Agent configuration

Please refer to the documentation in the deployment package for information about configuring the IBM agents to communicate with the IBM Monitoring Instana Integration Service.

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

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 Instana IBM Datapower sensor for the list of collected metrics from the IBM Datapower agent.

Note: the support for IBM Datapower metrics through this integration requires the Instana server to be Build 201 or higher.

Note: several metrics expected in the Instana Host and Datapower-related entities are not currently collected by the ITM V6 agents. These metrics will be blank or null in the Instana UI. A document is provided with the deployment package to help in mapping the metrics on the Instana UI to the ITM TEP UI.

Metrics are collected from the supported V6 agents attached to the IBM Monitoring Instana Integration Service and forwarded to Instana, resulting in the creation of Host and Datapower entities on the Instana UI.

Note: metrics are collected by the ITM V6 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 as they become available at the IBM Monitoring Instana Integration Service.

Health Signatures

Please refer to the ibm-apmproxy sensor documentation for the Health Signature information (https://www.instana.com/docs/ecosystem/ibm-apmproxy/#health-signatures)

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.

IBM Technology Preview

TECHNOLOGY PREVIEW CODE: Technology Preview Code (TPC) may be included or distributed with the Program or updates to it. TPC will be identified as such in the Notices File (or in an updated Notices File accompanying the updates), or in a file or files referenced in such Notices File. Some or all of the TPC may not be made generally available by IBM as or in a product. You are authorized to use the TPC only for internal use for evaluation purposes and not for use in a production environment. The Notices File may limit this evaluation use to an evaluation period. If so, at the end of such evaluation period, You must cease using and uninstall the TPC. No support is provided for TPC and it is provided on an "AS IS" BASIS WITHOUT WARRANTY OF ANY KIND (EXPRESS OR IMPLIED), INCLUDING,WITHOUT LIMITATION, ANY IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. You may not transfer TPC to another party. TPC may contain a disabling device that will prevent it from being used after the evaluation period ends. You will not tamper with this disabling device or the TPC. You should take precautions to avoid any loss of data that might result when the TPC can no longer be used.