IBM MQ monitoring integration

preview

We're still working on this feature, but we'd love for you to try it out!

This feature is currently provided as part of a preview program pursuant to our pre-release policies.

Our IBM MQ integration collects and sends dimensional metrics from IBM MQ.

You can view this metric data in pre-built dashboards, create alerts policies, and create custom queries and charts.

Image of the dashboard available through the IBM MQ quickstart

Dashboard installed through the New Relic IBM MQ Monitor quickstart.

To get data from IBM MQ infrastructure, our IBM MQ integration uses a third-party Prometheus exporter, which exposes Prometheus metrics on the port specified in the configuration. The integration collects these metrics, filters them, and then sends them to New Relic.

Important

The IBM MQ integration doesn't support ARM64 architecture.

To start set up the IBM MQ integration, follow these steps:

Configuration options

To configure the integration, edit the config in the integration's YAML config file, ibmmq-config.yml. An integration's YAML-format configuration is where you can place required login credentials and configure how to collect data. Which options you change depend on your setup and preference. The configuration file has common settings applicable to all integrations.

To read all about these common settings, refer to our configuration format document.

IBM MQ instance settings

The following configuration options are available:

Setting	Description	Default
`hostname`	Hostname of the IBM MQ service	N/A
`port`	Port of the IBM MQ service	N/A
`queue_manager`	Queue Manager name	N/A
`channel`	Channel name used to connect to the queue manager. Typically you can use `SYSTEM.DEF.SVRCONN`	N/A
`username`	Username to authenticate to IBM MQ service. If the password is not specified, user/password authentication is disabled and the username should not be specified in the configuration. The exporter will connect sending as `clientID` the user executing the integration. Depending on the agent installation mode it could be `root` or `nri-agent`.	N/A
`password`	Password to authenticate to IBM MQ service	N/A
`monitored_queues`	Queues to monitor (wildcards and `!` to exclude are accepted)	N/A
`monitored_channels`	Channels to monitor (wildcards and `!` to exclude are accepted)	N/A
`monitored_topics`	Topics to monitor (wildcards and `!` to exclude are accepted)	N/A
`monitored_subscriptions`	Subscriptions to monitor (wildcards and `!` to exclude are accepted)	N/A
`exporter_port`	Port to expose scrape endpoint on, If this is not provided a random port will be used to launch the exporter	`random-port`
`scrape_timeout`	Time until a scrape request times out	`5s`
`mqsslkeyr`	Needed to configure TLS `MQSSLKEYR` specifies the location of the keystore that holds the digital certificate belonging to the user or to the server. It should be specified without the extension to point to both `key.kdb` and `key.sth`.	N/A
`ccdt_url`	Needed to configure TLS Path to the ccdt file. Two different environment variable will be set automatically: `MQCCDTURL` and `IBMMQ_CONNECTION_CCDTURL`.	N/A
`home`	IBMMQ Client needs permissions to write in a directory specified in the `HOME` environment variable.	N/A
`ld_library_path`	`LD_LIBRARY_PATH` environment variable for the IBMMQ Client used by the exporter.	N/A

Examples of the `ibmmq-config.yml` file

This is the basic configuration used to collect metrics:

integrations:
  - name: nri-ibmmq
    config:
      hostname: localhost
      port: 1414
      queue_manager: QM1
      channel: SYSTEM.DEF.SVRCONN
      username: your_mq_user
      password: your_mq_password
      monitored_queues: '!SYSTEM.*,*'
      monitored_channels: '*'
      monitored_topics: '*'
      monitored_subscriptions: '*'
      exporter_port: 9157

This is the same basic configuration used to collect metrics showing how to run the integration twice connecting to two hosts. Notice that each instance of the integration will spawn an extra exporter listening on a different port.

integrations:
  - name: nri-ibmmq
    config:
      hostname: host1
      port: 1414
      queue_manager: QM1
      channel: SYSTEM.DEF.SVRCONN
      username: your_mq_user
      password: your_mq_password
      monitored_queues: '!SYSTEM.*,*'
      monitored_channels: '*'
      monitored_topics: '*'
      monitored_subscriptions: '*'
  - name: nri-ibmmq
    config:
      hostname: host2
      port: 1414
      queue_manager: QM1
      channel: SYSTEM.DEF.SVRCONN
      username: your_mq_user
      password: your_mq_password
      monitored_queues: '!SYSTEM.*,*'
      monitored_channels: '*'
      monitored_topics: '*'
      monitored_subscriptions: '*'

If the password is not specified, user/password authentication is disabled and you shouldn't specify the username in the configuration.

The exporter will try to connect sending as clientID the user executing the integration. Depending on the agent installation mode it could be root or nri-agent.

Such user needs to be able to access the queue manager without providing a password.

integrations:
  - name: nri-ibmmq
    config:
      hostname: localhost
      port: 1414
      queue_manager: QM1
      channel: SYSTEM.DEF.SVRCONN
      monitored_queues: '!SYSTEM.*,*'
      monitored_channels: '*'
      monitored_topics: '*'
      monitored_subscriptions: '*'
      exporter_port: 9157

This is the basic configuration using filters to restrict the monitored queues.
In this example we monitor all queues named DEV.QUEUE and specifically ignore queue DEV.QUEUE.1. You can add other patterns separated by commas:

integrations:
  - name: nri-ibmmq
    config:
      hostname: localhost
      port: 1414
      queue_manager: QM1
      channel: SYSTEM.DEF.SVRCONN
      username: your_mq_user
      password: your_mq_password
      monitored_queues: 'DEV.QUEUE*,!DEV.QUEUE.1'
      monitored_channels: '*'
      monitored_topics: '*'
      monitored_subscriptions: '*'
      exporter_port: 9157

This is an advanced configuration showing how to setup mTLS. The ccdt file should indicate which certificate to present to the server thorugh the certificateLabel field of the transmissionSecurity section. The certificate should be in the keystore with such label and trusted by the server. Morever, the Keystore should contain a certificate capable of verifying the one presented by the server.

integrations:
  - name: nri-ibmmq
    config:
      queue_manager: QM1
      channel: SYSTEM.DEF.SVRCONN
      username: your_mq_user
      password: your_mq_password
      monitored_queues: 'DEV.QUEUE*,!DEV.QUEUE.1'
      monitored_channels: '*'
      monitored_topics: '*'
      monitored_subscriptions: '*'
      exporter_port: 9157

      # Configuring mTLS
      mqsslkeyr: "/key"
      ccdt_url: "file:///ccdt.json"
      home: /tmp

Metric data

Two entities are created: IBMMQ_MANAGER and IBMMQ_QUEUE.

The following dimensional metrics are captured scraping the exporter and linked to the entity IBMMQ_MANAGER:

Name	Description	Dimensions
`ibmmq_channel_buffers_rcvd`	Buffers rcvd	rqmname type channel connname description jobname platform qmgr
`ibmmq_channel_buffers_sent`	Buffers sent	type channel connname description jobname platform qmgr rqmname
`ibmmq_channel_bytes_rcvd`	Bytes rcvd	description jobname platform qmgr rqmname type channel connname
`ibmmq_channel_bytes_sent`	Bytes sent	channel connname description jobname platform qmgr rqmname type
`ibmmq_channel_instance_type`	Channel Instance Type	connname description jobname platform qmgr rqmname type channel
`ibmmq_channel_messages`	Messages (API Calls for SVRCONN)	jobname platform qmgr rqmname type channel connname description
`ibmmq_channel_status`	Channel Status	jobname platform qmgr rqmname type channel connname description
`ibmmq_channel_status_squash`	Channel Status - Simplified	rqmname type channel connname description jobname platform qmgr
`ibmmq_channel_substate`	Channel Substate	description jobname platform qmgr rqmname type channel connname
`ibmmq_channel_time_since_msg`	Time Since Msg	platform qmgr rqmname type channel connname description jobname
`ibmmq_channel_type`	Channel Type	platform qmgr rqmname type channel connname description jobname
`ibmmq_qmgr_alter_durable_subscription_count`	Alter durable subscription count	platform qmgr
`ibmmq_qmgr_channel_initiator_status`	Channel Initiator Status	platform qmgr
`ibmmq_qmgr_command_server_status`	Command Server Status	qmgr platform
`ibmmq_qmgr_commit_count`	Commit count	platform qmgr
`ibmmq_qmgr_concurrent_connections_high_water_mark`	Concurrent connections - high water mark	platform qmgr
`ibmmq_qmgr_connection_count`	Connection Count	platform qmgr
`ibmmq_qmgr_cpu_load_fifteen_minute_average_percentage`	CPU load - fifteen minute average	platform qmgr
`ibmmq_qmgr_cpu_load_five_minute_average_percentage`	CPU load - five minute average	platform qmgr
`ibmmq_qmgr_cpu_load_one_minute_average_percentage`	CPU load - one minute average	platform qmgr
`ibmmq_qmgr_create_durable_subscription_count`	Create durable subscription count	platform qmgr
`ibmmq_qmgr_create_non_durable_subscription_count`	Create non-durable subscription count	platform qmgr
`ibmmq_qmgr_delete_durable_subscription_count`	Delete durable subscription count	platform qmgr
`ibmmq_qmgr_delete_non_durable_subscription_count`	Delete non-durable subscription count	qmgr platform
`ibmmq_qmgr_durable_subscriber_high_water_mark`	Durable subscriber - high water mark	qmgr platform
`ibmmq_qmgr_durable_subscriber_low_water_mark`	Durable subscriber - low water mark	platform qmgr
`ibmmq_qmgr_expired_message_count`	Expired message count	platform qmgr
`ibmmq_qmgr_exporter_publications`	How many resource publications processed	platform qmgr
`ibmmq_qmgr_failed_browse_count`	Failed browse count	platform qmgr
`ibmmq_qmgr_failed_create_alter_resume_subscription_count`	Failed create/alter/resume subscription count	platform qmgr
`ibmmq_qmgr_failed_mqcb_count`	Failed MQCB count	platform qmgr
`ibmmq_qmgr_failed_mqclose_count`	Failed MQCLOSE count	platform qmgr
`ibmmq_qmgr_failed_mqconn_mqconnx_count`	Failed MQCONN/MQCONNX count	platform qmgr
`ibmmq_qmgr_failed_mqget_count`	Failed MQGET - count	platform qmgr
`ibmmq_qmgr_failed_mqinq_count`	Failed MQINQ count	platform qmgr
`ibmmq_qmgr_failed_mqopen_count`	Failed MQOPEN count	platform qmgr
`ibmmq_qmgr_failed_mqput_count`	Failed MQPUT count	platform qmgr
`ibmmq_qmgr_failed_mqput1_count`	Failed MQPUT1 count	platform qmgr
`ibmmq_qmgr_failed_mqset_count`	Failed MQSET count	platform qmgr
`ibmmq_qmgr_failed_mqsubrq_count`	Failed MQSUBRQ count	platform qmgr
`ibmmq_qmgr_failed_topic_mqput_mqput1_count`	Failed topic MQPUT/MQPUT1 count	platform qmgr
`ibmmq_qmgr_got_non_persistent_messages_bytes`	Got non-persistent messages - byte count	platform qmgr
`ibmmq_qmgr_got_persistent_messages_bytes`	Got persistent messages - byte count	platform qmgr
`ibmmq_qmgr_interval_destructive_get_total_bytes`	Interval total destructive get - byte count	platform qmgr
`ibmmq_qmgr_interval_destructive_get_total_count`	Interval total destructive get- count	platform qmgr
`ibmmq_qmgr_interval_mqput_mqput1_total_bytes`	Interval total MQPUT/MQPUT1 byte count	platform qmgr
`ibmmq_qmgr_interval_mqput_mqput1_total_count`	Interval total MQPUT/MQPUT1 count	platform qmgr
`ibmmq_qmgr_interval_topic_put_total`	Interval total topic bytes put	platform qmgr
`ibmmq_qmgr_log_current_primary_space_in_use_percentage`	Log - current primary space in use	platform qmgr
`ibmmq_qmgr_log_file_system_in_use_bytes`	Log file system - bytes in use	platform qmgr
`ibmmq_qmgr_log_file_system_max_bytes`	Log file system - bytes max	platform qmgr
`ibmmq_qmgr_log_in_use_bytes`	Log - bytes in use	platform qmgr
`ibmmq_qmgr_log_logical_written_bytes`	Log - logical bytes written	platform qmgr
`ibmmq_qmgr_log_max_bytes`	Log - bytes max	platform qmgr
`ibmmq_qmgr_log_physical_written_bytes`	Log - physical bytes written	platform qmgr
`ibmmq_qmgr_log_workload_primary_space_utilization_percentage`	Log - workload primary space utilization	platform qmgr
`ibmmq_qmgr_log_write_latency_seconds`	Log - write latency	platform qmgr
`ibmmq_qmgr_log_write_size_bytes`	Log - write size	platform qmgr
`ibmmq_qmgr_mq_errors_file_system_free_space_percentage`	MQ errors file system - free space	platform qmgr
`ibmmq_qmgr_mq_errors_file_system_in_use_bytes`	MQ errors file system - bytes in use	platform qmgr
`ibmmq_qmgr_mq_fdc_file_count`	MQ FDC file count	platform qmgr
`ibmmq_qmgr_mq_trace_file_system_free_space_percentage`	MQ trace file system - free space	platform qmgr
`ibmmq_qmgr_mq_trace_file_system_in_use_bytes`	MQ trace file system - bytes in use	platform qmgr
`ibmmq_qmgr_mqcb_count`	MQCB count	platform qmgr
`ibmmq_qmgr_mqclose_count`	MQCLOSE count	qmgr platform
`ibmmq_qmgr_mqconn_mqconnx_count`	MQCONN/MQCONNX count	platform qmgr
`ibmmq_qmgr_mqctl_count`	MQCTL count	qmgr platform
`ibmmq_qmgr_mqdisc_count`	MQDISC count	qmgr platform
`ibmmq_qmgr_mqinq_count`	MQINQ count	platform qmgr
`ibmmq_qmgr_mqopen_count`	MQOPEN count	platform qmgr
`ibmmq_qmgr_mqset_count`	MQSET count	platform qmgr
`ibmmq_qmgr_mqstat_count`	MQSTAT count	platform qmgr
`ibmmq_qmgr_mqsubrq_count`	MQSUBRQ count	platform qmgr
`ibmmq_qmgr_non_durable_subscriber_high_water_mark`	Non-durable subscriber - high water mark	qmgr platform
`ibmmq_qmgr_non_durable_subscriber_low_water_mark`	Non-durable subscriber - low water mark	qmgr platform
`ibmmq_qmgr_non_persistent_message_browse_bytes`	Non-persistent message browse - byte count	platform qmgr
`ibmmq_qmgr_non_persistent_message_browse_count`	Non-persistent message browse - count	platform qmgr
`ibmmq_qmgr_non_persistent_message_destructive_get_count`	Non-persistent message destructive get - count	platform qmgr
`ibmmq_qmgr_non_persistent_message_mqput_count`	Non-persistent message MQPUT count	platform qmgr
`ibmmq_qmgr_non_persistent_message_mqput1_count`	Non-persistent message MQPUT1 count	platform qmgr
`ibmmq_qmgr_non_persistent_topic_mqput_mqput1_count`	Non-persistent - topic MQPUT/MQPUT1 count	platform qmgr
`ibmmq_qmgr_persistent_message_browse_bytes`	Persistent message browse - byte count	qmgr platform
`ibmmq_qmgr_persistent_message_browse_count`	Persistent message browse - count	platform qmgr
`ibmmq_qmgr_persistent_message_destructive_get_count`	Persistent message destructive get - count	platform qmgr
`ibmmq_qmgr_persistent_message_mqput_count`	Persistent message MQPUT count	platform qmgr
`ibmmq_qmgr_persistent_message_mqput1_count`	Persistent message MQPUT1 count	platform qmgr
`ibmmq_qmgr_persistent_topic_mqput_mqput1_count`	Persistent - topic MQPUT/MQPUT1 count	qmgr platform
`ibmmq_qmgr_published_to_subscribers_bytes`	Published to subscribers - byte count	platform qmgr
`ibmmq_qmgr_published_to_subscribers_message_count`	Published to subscribers - message count	platform qmgr
`ibmmq_qmgr_purged_queue_count`	Purged queue count	platform qmgr
`ibmmq_qmgr_put_non_persistent_messages_bytes`	Put non-persistent messages - byte count	platform qmgr
`ibmmq_qmgr_put_persistent_messages_bytes`	Put persistent messages - byte count	platform qmgr
`ibmmq_qmgr_queue_manager_file_system_free_space_percentage`	Queue Manager file system - free space	platform qmgr
`ibmmq_qmgr_queue_manager_file_system_in_use_bytes`	Queue Manager file system - bytes in use	platform qmgr
`ibmmq_qmgr_ram_free_percentage`	RAM free percentage	platform qmgr
`ibmmq_qmgr_ram_total_bytes`	RAM total bytes	platform qmgr
`ibmmq_qmgr_ram_total_estimate_for_queue_manager_bytes`	RAM total bytes - estimate for queue manager	platform qmgr
`ibmmq_qmgr_resume_durable_subscription_count`	Resume durable subscription count	platform qmgr
`ibmmq_qmgr_rollback_count`	Rollback count	platform qmgr
`ibmmq_qmgr_status`	Queue Manager Status	qmgr platform
`ibmmq_qmgr_subscription_delete_failure_count`	Subscription delete failure count	platform qmgr
`ibmmq_qmgr_system_cpu_time_estimate_for_queue_manager_percentage`	System CPU time - percentage estimate for queue manager	qmgr platform
`ibmmq_qmgr_system_cpu_time_percentage`	System CPU time percentage	qmgr platform
`ibmmq_qmgr_topic_mqput_mqput1_interval_total`	Topic MQPUT/MQPUT1 interval total	platform qmgr
`ibmmq_qmgr_uptime`	Up time	platform qmgr
`ibmmq_qmgr_user_cpu_time_estimate_for_queue_manager_percentage`	User CPU time - percentage estimate for queue manager	qmgr platform
`ibmmq_qmgr_user_cpu_time_percentage`	User CPU time percentage	platform qmgr
`ibmmq_subscription_messsages_received`	Messages Received	type platform qmgr subid subscription topic
`ibmmq_subscription_time_since_message_published`	Time Since Message Received	platform qmgr subid subscription topic type
`ibmmq_subscription_type`	Subscription Type	topic type platform qmgr subid subscription
`ibmmq_topic_messages_received`	Received Messages	platform qmgr topic type
`ibmmq_topic_publisher_count`	Number of publishers	platform qmgr topic type
`ibmmq_topic_subscriber_count`	Number of subscribers	platform qmgr topic type
`ibmmq_topic_time_since_msg_received`	Time Since Msg	platform qmgr topic type

The following dimensional metrics are captured scraping the exporter and linked to the entity IBMMQ_QUEUE:

Name	Description	Dimensions
`ibmmq_queue_attribute_max_depth`	Queue Max Depth	description platform qmgr queue usage
`ibmmq_queue_attribute_usage`	Queue Usage	platform qmgr queue usage description
`ibmmq_queue_average_queue_time_seconds`	average queue time	description platform qmgr queue usage
`ibmmq_queue_avoided_percentage`	queue avoided bytes	qmgr queue usage description platform
`ibmmq_queue_avoided_puts_percentage`	queue avoided puts	qmgr queue usage description platform
`ibmmq_queue_depth`	Queue depth	description platform qmgr queue usage
`ibmmq_queue_destructive_mqget_fails`	destructive MQGET fails	description platform qmgr queue usage
`ibmmq_queue_destructive_mqget_fails_with_mqrc_no_msg_available`	destructive MQGET fails with MQRC_NO_MSG_AVAILABLE	platform qmgr queue usage description
`ibmmq_queue_destructive_mqget_fails_with_mqrc_truncated_msg_failed`	destructive MQGET fails with MQRC_TRUNCATED_MSG_FAILED	description platform qmgr queue usage
`ibmmq_queue_destructive_mqget_non_persistent_bytes`	destructive MQGET non-persistent byte count	queue usage description platform qmgr
`ibmmq_queue_destructive_mqget_non_persistent_message_count`	destructive MQGET non-persistent message count	usage description platform qmgr queue
`ibmmq_queue_destructive_mqget_persistent_bytes`	destructive MQGET persistent byte count	description platform qmgr queue usage
`ibmmq_queue_destructive_mqget_persistent_message_count`	destructive MQGET persistent message count	description platform qmgr queue usage
`ibmmq_queue_expired_messages`	messages expired	platform qmgr queue usage description
`ibmmq_queue_input_handles`	Input Handles	platform qmgr queue usage description
`ibmmq_queue_lock_contention_percentage`	lock contention	description platform qmgr queue usage
`ibmmq_queue_mqclose_count`	MQCLOSE count	queue usage description platform qmgr
`ibmmq_queue_mqget_browse_fails`	MQGET browse fails	queue usage description platform qmgr
`ibmmq_queue_mqget_browse_fails_with_mqrc_no_msg_available`	MQGET browse fails with MQRC_NO_MSG_AVAILABLE	description platform qmgr queue usage
`ibmmq_queue_mqget_browse_fails_with_mqrc_truncated_msg_failed`	MQGET browse fails with MQRC_TRUNCATED_MSG_FAILED	platform qmgr queue usage description
`ibmmq_queue_mqget_browse_non_persistent_bytes`	MQGET browse non-persistent byte count	qmgr queue usage description platform
`ibmmq_queue_mqget_browse_non_persistent_message_count`	MQGET browse non-persistent message count	description platform qmgr queue usage
`ibmmq_queue_mqget_browse_persistent_bytes`	MQGET browse persistent byte count	description platform qmgr queue usage
`ibmmq_queue_mqget_browse_persistent_message_count`	MQGET browse persistent message count	queue usage description platform qmgr
`ibmmq_queue_mqget_bytes`	MQGET byte count	platform qmgr queue usage description
`ibmmq_queue_mqget_count`	MQGET count	description platform qmgr queue usage
`ibmmq_queue_mqinq_count`	MQINQ count	description platform qmgr queue usage
`ibmmq_queue_mqopen_count`	MQOPEN count	description platform qmgr queue usage
`ibmmq_queue_mqput_bytes`	MQPUT byte count	description platform qmgr queue usage
`ibmmq_queue_mqput_mqput1_count`	MQPUT/MQPUT1 count	platform qmgr queue usage description
`ibmmq_queue_mqput_non_persistent_message_count`	MQPUT non-persistent message count	description platform qmgr queue usage
`ibmmq_queue_mqput_persistent_message_count`	MQPUT persistent message count	description platform qmgr queue usage
`ibmmq_queue_mqput1_non_persistent_message_count`	MQPUT1 non-persistent message count	description platform qmgr queue usage
`ibmmq_queue_mqput1_persistent_message_count`	MQPUT1 persistent message count	description platform qmgr queue usage
`ibmmq_queue_mqset_count`	MQSET count	description platform qmgr queue usage
`ibmmq_queue_non_persistent_bytes`	non-persistent byte count	description platform qmgr queue usage
`ibmmq_queue_oldest_message_age`	Oldest Message	description platform qmgr queue usage
`ibmmq_queue_output_handles`	Input Handles	usage description platform qmgr queue
`ibmmq_queue_persistent_bytes`	persistent byte count	qmgr queue usage description platform
`ibmmq_queue_purged_count`	queue purged count	description platform qmgr queue usage
`ibmmq_queue_qfile_current_size`	Queue File Current Size	description platform qmgr queue usage
`ibmmq_queue_qfile_max_size`	Queue File Maximum Size	qmgr queue usage description platform
`ibmmq_queue_qtime_long`	Queue Time Long	platform qmgr queue usage description
`ibmmq_queue_qtime_short`	Queue Time Short	platform qmgr queue usage description
`ibmmq_queue_rolled_back_mqget_count`	rolled back MQGET count	qmgr queue usage description platform
`ibmmq_queue_rolled_back_mqput_count`	rolled back MQPUT count	queue usage description platform qmgr
`ibmmq_queue_time_since_get`	Time Since Get	usage description platform qmgr queue
`ibmmq_queue_time_since_put`	Time Since Put	description platform qmgr queue usage
`ibmmq_queue_uncommitted_messages`	Uncommitted Messages (Count)	description platform qmgr queue usage