IBM MQ tracing

Dynatrace can automatically create a continuous Service flow for IBM MQ when the producer and consumer services use the same queue or topic name. If the producer and consumer services refer to different queue or topic names, IBM MQ configuration might be required to create a continuous service flow.

Without IBM MQ configuration, Dynatrace can still trace all messages, but the service flow will be broken.

Technology IBM MQ message IBM MQ configuration required

Technology	IBM MQ message	IBM MQ configuration required
z/OS Java .NET
IBM App Connect EnterpriseIBM Integration Bus	`MQRFH2.usr` folder not present `MQRFH2.usr` folder present

z/OS Java .NET

IBM App Connect EnterpriseIBM Integration Bus

MQRFH2.usr folder not present

MQRFH2.usr folder present

IBM MQ continuous service flow example

IBM MQ distributed trace example

FAQ

Should I create the MQRFH2 header when it is not present in my IBM MQ messages?

We recommend that you create the MQRFH2 header for IBM MQ messages. The presence of the MQRFH2 header in your IBM MQ messages allows Dynatrace to use identifiers instead of unique keys to trace messages across queues and topics of IBM App Connect Enterprise and IBM Integration Bus.

Benefits of creating the MQRFH2 header for IBM MQ messages include:

Consistent adaptive traffic management and control across your monitoring environment, lowering the volume on IBM MQ traces.
An accurate and continuous service flow without the need to configure IBM MQ mapping when the messages are solely processed by IBM App Connect Enterprise and IBM Integration Bus.

How can I create the MQRFH2 header when it is not present in my IBM MQ messages?

When the MQRFH2 header is present in your messages before an MQOutput node is called by IBM App Connect Enterprise or IBM Integration Bus, Dynatrace uses identifiers instead of unique keys to trace IBM MQ messages.

If this isn't the case in your environment, you can create an empty MQRFH2 header by, for example, executing the following ESQL command by a preceding Compute node

console
CREATE LASTCHILD of OutputRoot DOMAIN 'MQRFH2';

For Dynatrace, an empty MQRFH2 header is enough to automatically create the usr folder and to add Dynatrace identifiers to it. If a usr folder is already present, Dynatrace reuses it.

Specifications

Dynatrace creates the usr folder within the existing MQRFH2 header, not the MQRFH2 header itself.
When creating the usr folder, Dynatrace adds it at the beginning of the MQRFH2 header.
If the usr folder exists, Dynatrace adds its identifiers at the beginning of the usr folder.

Manage IBM MQ configuration

You can manage an IBM MQ configuration automatically by installing an IBM MQ extension and activating Retrieve topology for improved transaction tracing to retrieve the IBM MQ configuration of your environment and send it to the Settings API. This can also be done manually via the web UI or the Settings API.

Manual configuration via web UI

To manage the IBM MQ configuration via the Dynatrace web UI, from the Dynatrace menu, go to Settings > Mainframe to find the following menu options:

IBM MQ queue managers
IBM MQ queue sharing groups
IBM MQ IMS bridges

Manual configuration via Settings API

You can manage the IBM MQ configuration via the Dynatrace Settings API.

To be able to use the API you need an access token with Read settings (settings.read) and Write settings (settings.write) scopes. To learn how to obtain it, see Create an access token.

Configuration items

The table lists the available IBM MQ configuration items for queues and topics.

Item	Description	Your action
Queue manager	Queue manager with its queues	Define your queue managers, including alias queues, remote queues, and cluster queues within a single configuration item.
z/OS Queue sharing group	Group of queue managers that access the same shared queues	Specify which queue managers and shared queues belong to a queue-sharing group within a single configuration item.
z/OS IMS bridge	The IBM MQ component that allows direct access to the IMS system	Specify which queue managers and queues belong to an IMS bridge within a single configuration item.

Follow the procedures below to create or update a configuration item. Note that the scope of these items is always an environment. Before starting, learn the format of the settings object by querying its schema via the GET a schema call.

Create a configuration itemUpdate an existing configuration item

New queue manager

The ID of the queue manager schema is builtin:ibmmq.queue-managers.

Create the JSON object for your settings.

Note: The aliasQueues object can be a local queue owned by this queue manager, a local definition of a remote queue, or a cluster queue visible by this queue manager but owned by another queue manager.

Example JSON

json
[
  {
    "schemaId": "builtin:ibmmq.queue-managers",
    "scope": "environment",
    "value": {
      "name": "Queue Manager 1",
      "clusters": [
        "Name of the cluster this Queue Manager 1 is part of"
      ],
      "aliasQueues": [
        {
          "aliasQueue": "Alias Queue",
          "baseQueue": "Base queue which the Alias Queue should point to",
          "clusterVisibility": [
            "Name of a cluster this Alias Queue should be visible in (the queue manager must be part of this cluster)"
          ]
        }
      ],
      "remoteQueues": [
        {
          "localQueue": "Local definition of the Remote Queue",
          "remoteQueue": "Remote Queue",
          "remoteQueueManager": "Remote Queue Manager",
          "clusterVisibility": [
            "Name of a cluster this local definition of the Remote Queue should be visible in (the queue manager must be part of this cluster)"
          ]
        }
      ],
      "clusterQueues": [
        {
          "localQueue": "Local Queue",
          "clusterVisibility": [
            "Name of a cluster this Local Queue should be visible in (the queue manager must be part of this cluster)"
          ]
        }
      ]
    }
  }
]

Use the POST an object endpoint to send your configuration.

New queue sharing group

The ID of the queue sharing group schema is builtin:ibmmq.queue-sharing-group.

Create the JSON object for your settings.

Example JSON

json
[
  {
    "schemaId": "builtin:ibmmq.queue-sharing-group",
    "scope": "environment",
    "value": {
      "name": "Queue Sharing Group",
      "queueManagers": [
        "Queue Manager 1",
        "Queue Manager 2"
      ],
      "sharedQueues": [
        "Shared Queue 1",
        "Shared Queue 2"
      ]
    }
  }
]

Use the POST an object endpoint to send your configuration.

New IMS bridge

The ID of the IMS bridge schema is builtin:ibmmq.ims-bridges.

Create the JSON object for your settings.

Example JSON

json
[
  {
    "schemaId": "builtin:ibmmq.ims-bridges",
    "scope": "environment",
    "value": {
      "name": "IMS Bridge",
      "queueManagers": [
        {
          "name": "Queue Manager",
          "queueManagerQueue": [
            "Queue 1",
            "Queue 2"
          ]
        }
      ]
    }
  }
]

Use the POST an object endpoint to send your configuration.

Update queue manager

The ID of the queue manager schema is builtin:ibmmq.queue-managers.

Query the current configuration via the GET objects call.

Create the JSON for your update.

Use the updateToken value from the previous step.

Modify the values as needed.

Example JSON

json
{
  "updateToken": "vu9U3hXY3q0ATAAkMG",
  "value": {
    "name": "Queue Manager A",
    "clusters": [
      "Name of a cluster this Queue Manager A is part of"
    ],
    "aliasQueues": [
      {
        "aliasQueue": "Alias Queue",
        "baseQueue": "Base queue which the Alias Queue should point to",
        "clusterVisibility": [
          "Name of a cluster this Alias Queue should be visible in (the queue manager must be part of this cluster)"
        ]
      }
    ],
    "remoteQueues": [
      {
        "localQueue": "Local definition of the Remote Queue",
        "remoteQueue": "Remote Queue",
        "remoteQueueManager": "Remote Queue Manager",
        "clusterVisibility": [
          "Name of a cluster this local definition of the Remote Queue should be visible in (the queue manager must be part of this cluster)"
        ]
      }
    ],
    "clusterQueues": [
      {
        "localQueue": "Local Queue",
        "clusterVisibility": [
          "Name of a cluster this Local Queue should be visible in (the queue manager must be part of this cluster)"
        ]
      }
    ]
  }
}

Use the PUT an object endpoint to send your configuration.

Update sharing group

The ID of the queue sharing group schema is builtin:ibmmq.queue-sharing-group.

Query the current configuration via the GET objects call.

Create the JSON for your update.

Use the updateToken value from the previous step.

Modify the values as needed.

Example JSON

json
{
  "updateToken": "vu9U3hXY3q0ATAAkMG",
  "value": {
    "name": "Queue Sharing Group",
    "queueManagers": [
      "Queue Manager A",
      "Queue Manager B"
    ],
    "sharedQueues": [
      "Shared Queue A",
      "Shared Queue B"
    ]
  }
}

Use the PUT an object endpoint to send your configuration.

Update IMS bridge

The ID of the IMS bridge schema is builtin:ibmmq.ims-bridges.

Query the current configuration via the GET objects call.

Create the JSON for your update.

Use the updateToken value from the previous step.

Modify the values as needed.

Example JSON

json
{
  "updateToken": "vu9U3hXY3q0ATAAkMG",
  "value": {
    "name": "IMS Bridge",
    "queueManagers": [
      {
        "name": "Queue Manager",
        "queueManagerQueue": [
          "Queue A",
          "Queue B"
        ]
      }
    ]
  }
}

Use the PUT an object endpoint to send your configuration.