[OpenShift Container Platform][IBM Cloud Pak for Integration][IBM MQ Operator 2.2.0]

Integrating IBM MQ with IBM Instana tracing

IBM® Instana can be used to trace transactions within IBM Cloud Pak® for Integration.

Before you begin

This document covers IBM Instana tracing, which is the process of tracing messages through a system. It does not cover IBM Instana monitoring, in which detail is retrieved about the state of an IBM MQ queue manager. For information regarding monitoring of IBM MQ by IBM Instana see Monitoring IBM MQ. For detailed instructions on authenticated monitoring, see Configuring authenticated IBM Instana monitoring with TLS.

Note:
  • This feature can only be used with the IBM MQ Operator version 2.2.0 and later. This feature is supported only on Operands of IBM MQ version 9.3.1.0-r2 or later.
  • You can run IBM Instana tracing on previous IBM MQ Operator and queue manager versions, but not natively. See Configuring IBM MQ Tracing in the IBM Instana documentation.

Before you can perform IBM Instana tracing with the IBM MQ Operator, you must deploy both an IBM Instana backend and IBM Instana agents. By default, an IBM MQ queue manager communicates with an IBM Instana agent deployed on the same node as the queue manager pod.

About this task

Enabling integration with IBM Instana causes an IBM MQ API exit to be installed in your queue manager. The API exit sends tracing data to IBM Instana agents about messages that are flowing through the queue manager.

The API exit adds RFH2 headers to each message. These headers contain tracing information.

The IBM Instana agents are responsible for sending the tracing data to the IBM Instana backend.

For information about deploying an IBM Instana backend and IBM Instana agents, see Enabling IBM Instana monitoring in the CP4I Platform UI in the IBM Instana documentation.

Procedure

Standard Deployment

  • Deploy a queue manager with IBM Instana tracing enabled.

    By default, IBM Instana tracing is disabled.

    If you are using the IBM Cloud Pak for Integration Platform UI (previously the Platform Navigator) or the OpenShift® web console:
    1. Click Telemetry > Tracing > Instana.
    2. Set the Enable Instana tracing toggle to true.
    If you are deploying through YAML, use the following snippet:
    spec:
  telemetry:
    tracing:
      instana:
        enabled: true

Advanced Deployment

  • Communicate with the IBM Instana agent over https.

    By default, the IBM Instana exit for IBM MQ communicates with the IBM Instana agent over http. The agent's host address is set to the IP address of the node the queue manager is running on. This matches the configuration described in Enabling IBM Instana monitoring in the IBM Instana documentation, where IBM Instana agents are deployed by the IBM Instana Agent Operator as a daemonset.

    Currently the communication between the IBM Instana exit for IBM MQ and the IBM Instana agent supports http or https protocols. To use https, the IBM Instana agent must first be configured to use TLS encryption. See Setting up TLS encryption for Agent endpoint in the IBM Instana documentation. The protocol can then be set to https as follows:

    If you are using the OpenShift web console:
    1. Click Telemetry > Instana.
    2. Expand the Advanced configuration dropdown list.
    3. Set the Instana agent communication protocol to https.
    If you are deploying through YAML, use the following snippet:
    spec:
  telemetry:
    instana:
      enabled: true
      protocol: https
  • Set the agentHost

    If IBM Instana agents have not been deployed as a daemonset on the Openshift cluster where the queue manager is running, then you must set the agentHost value to the hostname or IP address where the IBM Instana agent is running. The agentHost value should not include a protocol or port.

    If you are using the OpenShift web console:
    1. Click Telemetry > Instana.
    2. Expand the Advanced configuration dropdown list.
    3. Type your hostname into the Instana agent host text box.
    If you are deploying through YAML, use the following snippet:
    spec:
  telemetry:
    instana:
      enabled: true
      agentHost: 9.9.9.9

What to do next

See also Deploying a queue manager onto a Red Hat OpenShift Container Platform cluster.