Add metric ibm_mq.channel.conns to ibm mq integration, add channel and connection metric tests (DataDog#20519)

* add metric ibm_mq.channel.conns, add channel and connection metric tests

* Add changelog entry

* run black formatting

* apply ruff check --config ../pyproject.toml --fix

* fix(ibm_mq): use correct metrics for channel status collection

- Update channel metric collector to use channel_status_metrics() instead of channel_metrics()
  for discovered channels to properly collect buffers_rcvd metric
- Update test assertions to match actual tags being sent in gauge calls
- Fix unit tests in test_channel_metric_collector.py to pass

This change ensures that channel status metrics like buffers_rcvd are properly
collected and reported by the integration.

* reformat test_channel_metric_collector.py using black

* Fix channel metric collection logic and update unit tests

- Updated get_pcf_channel_metrics to submit configuration metrics instead of status metrics.
- Modified unit tests to verify that configuration metrics are collected for channels with empty or no connections.
- Added a new test test_channel_status_metrics to ensure status metrics and connection metrics are correctly submitted.

* add ibm_mq.channel.conns to metadata.csv

* sort metadata.csv by metric name

* - rename ibm_mq.channel.conns to ibm_mq.channel.conn_status
- create new metric ibm_mq.channel.connections_active which represents total num of active conns per channel

* Test commit signing

* remove test_signing.txt

* reformat with black

* sorted metadata.csv with ddev validate metadata ibm_mq --sync

* fix and sort metadata.csv; many metrics had been removed accidentally

* shorten changelog entry

* add config option collect_connection_metrics so that metric ibm_mq.channel.conn_status is only collected if this flag is enabled

* Update ibm_mq/assets/configuration/spec.yaml

Co-authored-by: Bryce Eadie <bryce.eadie@datadoghq.com>

* Update ibm_mq/datadog_checks/ibm_mq/data/conf.yaml.example

Co-authored-by: Bryce Eadie <bryce.eadie@datadoghq.com>

* fix formatting with ddev test --fmt

* format with ddev test --fmt

* reformat with ddev test --fmt after upgrading ddev

* move simulate_mq_conn.py, add description, add licensing comment

* fix license header with ddev validate license-headers ibm_mq/tests/agent_scripts/ --fix

---------

Co-authored-by: Bryce Eadie <bryce.eadie@datadoghq.com>

Author: mwdd146980

ibm_mq/assets/configuration/spec.yaml

@@ -187,6 +187,17 @@ files:
         value:
           example: true
           type: boolean
+      - name: collect_connection_metrics
+        description: |
+          Collect connection-related metrics. Metrics collected are:
+            - connection status metrics (ibm_mq.channel.conn_status)
+
+          Note: Enabling this option increases tag cardinality, as the ibm_mq.channel.conn_status
+          metric creates a new `connection` tag for each unique connection. This can lead to high
+          cardinality if you have many active connections.
+        value:
+          example: false
+          type: boolean
       - name: mqcd_version
         description: |
           Which channel definition version to use. Supported values are 1 to 9 including.

ibm_mq/changelog.d/20519.added

@@ -0,0 +1 @@
+Add ibm_mq.channel.conn_status and ibm_mq.channel.connections_active metrics with channel and connection metric tests

ibm_mq/datadog_checks/ibm_mq/collectors/channel_metric_collector.py

@@ -146,6 +146,8 @@ def _submit_channel_status(self, queue_manager, search_channel_name, tags, chann
                 )
                 self.log.warning("Error getting CHANNEL status for channel %s: %s", search_channel_name, e)
         else:
+            # Count active connections per channel
+            channel_active_counts = {}
             for channel_info in response:
                 channel_name = to_string(channel_info[pymqi.CMQCFC.MQCACH_CHANNEL_NAME]).strip()
                 if channel_name in channels_to_skip:
@@ -159,6 +161,18 @@ def _submit_channel_status(self, queue_manager, search_channel_name, tags, chann
                 channel_status = channel_info[pymqi.CMQCFC.MQIACH_CHANNEL_STATUS]
                 self._submit_channel_count(channel_name, channel_status, channel_tags)
                 self._submit_status_check(channel_name, channel_status, channel_tags)
+
+                # Count as active connection if status is MQCHS_RUNNING
+                if channel_status == pymqi.CMQCFC.MQCHS_RUNNING:
+                    channel_active_counts[channel_name] = channel_active_counts.get(channel_name, 0) + 1
+            # Submit the total active connections for each channel
+            for channel_name, active_count in channel_active_counts.items():
+                self.gauge(
+                    '{}.channel.connections_active'.format(metrics.METRIC_PREFIX),
+                    active_count,
+                    tags=tags + ["channel:{}".format(channel_name)],
+                    hostname=self.config.hostname,
+                )
         finally:
             if pcf is not None:
                 pcf.disconnect()
@@ -170,6 +184,19 @@ def _submit_metrics_from_properties(self, channel_info, channel_name, metrics_ma
             if pymqi_type not in channel_info:
                 self.log.debug("metric '%s' not found in channel: %s", metric_name, channel_name)
                 continue
+
+            # Special handling for connection metric
+            if metric_name == 'conn_status':
+                if not self.config.collect_connection_metrics:
+                    continue
+                connection_name = to_string(channel_info[pymqi_type]).strip()
+                if not connection_name:
+                    continue
+                connection_tags = tags + ["connection:{}".format(connection_name)]
+                self.gauge(metric_full_name, 1, tags=connection_tags, hostname=self.config.hostname)
+                continue
+
+            # Regular metric handling
             metric_value = int(channel_info[pymqi_type])
             self.gauge(metric_full_name, metric_value, tags=tags, hostname=self.config.hostname)
 

ibm_mq/datadog_checks/ibm_mq/config.py

@@ -83,6 +83,7 @@ def __init__(self, instance, init_config):
 
         self.collect_statistics_metrics = is_affirmative(instance.get('collect_statistics_metrics', False))  # type: bool
         self.collect_reset_queue_metrics = is_affirmative(instance.get('collect_reset_queue_metrics', True))
+        self.collect_connection_metrics = is_affirmative(instance.get('collect_connection_metrics', True))
         if int(self.auto_discover_queues) + int(bool(self.queue_patterns)) + int(bool(self.queue_regex)) > 1:
             self.log.warning(
                 "Configurations auto_discover_queues, queue_patterns and queue_regex are not intended to be used "

ibm_mq/datadog_checks/ibm_mq/config_models/defaults.py

@@ -20,6 +20,10 @@ def instance_auto_discover_queues():
     return False
 
 
+def instance_collect_connection_metrics():
+    return False
+
+
 def instance_collect_reset_queue_metrics():
     return True
 

ibm_mq/datadog_checks/ibm_mq/config_models/instance.py

@@ -40,6 +40,7 @@ class InstanceConfig(BaseModel):
     channel: str = Field(..., min_length=1)
     channel_status_mapping: Optional[MappingProxyType[str, Any]] = None
     channels: Optional[tuple[str, ...]] = None
+    collect_connection_metrics: Optional[bool] = None
     collect_reset_queue_metrics: Optional[bool] = None
     collect_statistics_metrics: Optional[bool] = None
     connection_name: Optional[str] = Field(None, min_length=1)

ibm_mq/datadog_checks/ibm_mq/data/conf.yaml.example

@@ -167,6 +167,16 @@ instances:
     #
     # collect_reset_queue_metrics: true
 
+    ## @param collect_connection_metrics - boolean - optional - default: false
+    ## Collect connection-related metrics. Metrics collected are:
+    ##   - connection status metrics (ibm_mq.channel.conn_status)
+    ##
+    ## Note: Enabling this option increases tag cardinality, as the ibm_mq.channel.conn_status
+    ## metric creates a new `connection` tag for each unique connection. This can lead to high
+    ## cardinality if you have many active connections.
+    #
+    # collect_connection_metrics: false
+
     ## @param mqcd_version - number - optional - default: 6
     ## Which channel definition version to use. Supported values are 1 to 9 including.
     ## If you're having connection issues make sure it matches your MQ version.

ibm_mq/datadog_checks/ibm_mq/metrics.py

@@ -109,6 +109,7 @@ def channel_status_metrics():
         'batches': pymqi.CMQCFC.MQIACH_BATCHES,
         'current_msgs': pymqi.CMQCFC.MQIACH_CURRENT_MSGS,
         'indoubt_status': pymqi.CMQCFC.MQIACH_INDOUBT_STATUS,
+        'conn_status': pymqi.CMQCFC.MQCACH_CONNECTION_NAME,
     }
 
 

ibm_mq/metadata.csv

@@ -8,6 +8,8 @@ ibm_mq.channel.bytes_rcvd,gauge,,byte,,This attribute specifies the number of by
 ibm_mq.channel.bytes_sent,gauge,,byte,,This attribute specifies the number of bytes sent (parameter identifier: `MQIACH_BYTES_SENT`).,0,ibm_mq,bytes sent,
 ibm_mq.channel.channel_status,gauge,,,,This attribute specifies the channel status (parameter identifier: `MQIACH_CHANNEL_STATUS`).,0,ibm_mq,channel status,
 ibm_mq.channel.channels,gauge,,resource,,The number of active channels.,0,ibm_mq,active channel count,
+ibm_mq.channel.conn_status,gauge,,connection,,The connection status for the channel (parameter identifier: `MQIACH_CONNS`).,0,ibm_mq,conn status,
+ibm_mq.channel.connections_active,gauge,,connection,,The total number of active channel connections (instances) per channel.,0,ibm_mq,connections active,
 ibm_mq.channel.count,gauge,,,,Sum by status to count channels. Filter by channel and status tags to create notifications.,0,ibm_mq,channel count,
 ibm_mq.channel.current_msgs,gauge,,message,,This attribute specifies the number of messages in-doubt (parameter identifier: `MQIACH_CURRENT_MSGS`).,0,ibm_mq,current msgs,
 ibm_mq.channel.disc_interval,gauge,,second,,"This attribute is the length of time after which a channel closes down, if no message arrives during that period (parameter identifier: `DISCINT`).",0,ibm_mq,disc interval,

ibm_mq/tests/agent_scripts/simulate_mq_conn.py

@@ -0,0 +1,51 @@
+# (C) Datadog, Inc. 2025-present
+# All rights reserved
+# Licensed under a 3-clause BSD style license (see LICENSE)
+"""
+IBM MQ Connection Simulation Script
+
+This script simulates an active connection to an IBM MQ queue manager for manual testing purposes.
+It connects to a specified queue manager, puts a message to a queue, and maintains the connection
+for 120 seconds to simulate an active channel connection.
+
+This script was used for manual testing of the IBM MQ integration PR that adds connection-related
+metrics (ibm_mq.channel.conn_status and ibm_mq.channel.connections_active). By creating active
+connections, we can verify that the new metrics properly detect and count channel connections.
+
+Usage: python simulate_mq_conn.py <QMGR> <CHANNEL> <HOST> <PORT> <QUEUE> [<MESSAGE>] [<USER>] [<PASSWORD>]
+Example: python simulate_mq_conn.py QM1 GCP.A localhost 11414 APP.QUEUE.1 "Hello from script" admin passw0rd
+"""
+
+import sys
+import time
+
+import pymqi
+
+# Usage: python simulate_mq_conn.py <QMGR> <CHANNEL> <HOST> <PORT> <QUEUE> [<MESSAGE>] [<USER>] [<PASSWORD>]
+# Example: python simulate_mq_conn.py QM1 GCP.A localhost 11414 APP.QUEUE.1 "Hello from script" admin passw0rd
+
+qmgr_name = sys.argv[1] if len(sys.argv) > 1 else "QM1"
+channel = sys.argv[2] if len(sys.argv) > 2 else "DEV.ADMIN.SVRCONN"
+host = sys.argv[3] if len(sys.argv) > 3 else "localhost"
+port = sys.argv[4] if len(sys.argv) > 4 else "11414"
+queue_name = sys.argv[5] if len(sys.argv) > 5 else "APP.QUEUE.1"
+message = sys.argv[6] if len(sys.argv) > 6 else "Hello from pymqi!"
+user = sys.argv[7] if len(sys.argv) > 7 else "admin"
+password = sys.argv[8] if len(sys.argv) > 8 else "passw0rd"
+
+conn_info = f"{host}({port})"
+
+print(f"Connecting to {qmgr_name} on {host}:{port} via channel {channel} as {user}...")
+
+qmgr = pymqi.connect(qmgr_name, channel, conn_info, user, password)
+queue = pymqi.Queue(qmgr, queue_name)
+
+print(f"Putting message: {message}")
+queue.put(message)
+
+print("Sleeping for 120 seconds to keep the connection open...")
+time.sleep(120)
+
+queue.close()
+qmgr.disconnect()
+print("Connection closed.")