Tracking IBM MQ to CICS

To track IBM® MQ to CICS® transactions end-to-end with Instana, you need to complete the following configuration task depending on your JMS/IBM MQ application setup. With the PTF UJ08777, an option is provided for monitoring IBM MQ to CICS transactions that do not require a change to the existing CICS/COBOL applications.

Before you begin

For the Instana agent side, Instana supports both Automatic Instrumentation and Manual Instrumentation. Either instrumentation can be used depending on your application need. To track IBM MQ or JMS messages that are consumed by CICS transactions, Instana agent needs to be configured if Instana AutoTrace is NOT adding tracing data to your application.

Note: Here is an example where Autotrace may work: for IBM MQ/JMS servlet applications, the Instana agent will successfully use Auto Tracing to detect JMS messages since Java is a supported technology for AutoTrace.

Procedure

Set the targetclient property on the JMS Destination to the value 0.

The agent puts a tracking token (also called a trace correlation header) into the message's MQRFH2 header which must be intact when the message arrives on the MQ queue.

targetclient property value	Meaning
`0`	Messages put on the destination queue contain the MQRFH2 header. Specify this value so that the MQRFH2 header does not get stripped off of the message when sent to the z/OS destination queue.
`1`	Messages put on the destination queue do not contain the MQRFH2 header (that contains the Instana trace correlation header). If this value is specified, no transaction monitoring will happen for the client application. Without the header, Z APM Connect cannot track anything.

Optional: Update Instana agent setting.
If Instana Autotrace does not work, additional configuration is needed. For IBM MQ/JMS applications that do not initiate transactions via HTTP calls, special configuration must be in place in the Instana agent to monitor the transactions. For more information, see Java trace SDK documentation. An example is shown below that updates the configuration.yaml file of the Instana agent to monitor the messages of a particular application.
```
# Java Tracing
com.instana.plugin.javatrace:
instrumentation:
    sdk:
      targets:
        - match:
            type: class
            name: MQSample
            method: 'sendMessage'
        span:
            name: 'MQSampleSpan'
            type: ENTRY            
```
Configure the z/OS MQ queue property control setting.
In this step, two configuration options are provided. You can choose the option that suits your needs better.
Note: The configuration will take effect only if targetclient is set to 0 in Step 1.
- Option 1: Required to update existing CICS/COBOL applications:
  1. Set the property control property attribute to the value COMPAT so that the RFH2 header will be passed to the CICS application.
  2. Update the application to either:
    - handle the RHF2 header,
    - or set the GMO property to the option MQGMO_NO_PROPERTIES (none) on the MQGET.
- Option 2: No need to update existing CICS/COBOL applications:
  Set the property control property attribute to the value NONE.
  Note: If a QALIAS (ALIAS queue) is used by the getting application then the ALIAS queue must use the property control attribute value NONE. In this case, the base queue must also use the property control attribute value NONE.
  
  In this setting, MQ will strip the RFH2 header before the message is passed to CICS, so no CICS application changes will be needed. In this case, Z APM Connect will intercept the header before MQ strips it off and use it for continued end-to-end tracking of the transaction.