New announcements for Serverless, Network, RUM, and more from Dash! New announcements from Dash!

IBM MQ

Agent Check Agent Check

Supported OS: Linux

Overview

This check monitors IBM MQ.

Setup

Follow the instructions below to install and configure this check for an Agent running on a host. For containerized environments, see the Autodiscovery Integration Templates for guidance on applying these instructions.

Installation

The IBM MQ check is included in the Datadog Agent package.

In order to use the IBM MQ check, you need to:

  1. Make sure the IBM MQ Client is installed (unless the IBM MQ server is already installed)
  2. Update your LD_LIBRARY_PATH to include the location of the libraries

For example:

export LD_LIBRARY_PATH=/opt/mqm/lib64:/opt/mqm/lib:$LD_LIBRARY_PATH

Note: Agent 6 uses Upstart or systemd to orchestrate the datadog-agent service. Environment variables may need to be added to the service configuration files at the default locations of /etc/init/datadog-agent.conf (Upstart) or /lib/systemd/system/datadog-agent.service (systemd). See documentation on Upstart or systemd for more information on how to configure these settings.

Here’s an example of the configuration that’s used for systemd:

[Unit]
Description="Datadog Agent"
After=network.target
Wants=datadog-agent-trace.service datadog-agent-process.service
StartLimitIntervalSec=10
StartLimitBurst=5

[Service]
Type=simple
PIDFile=/opt/datadog-agent/run/agent.pid
Environment="LD_LIBRARY_PATH=/opt/mqm/lib64:/opt/mqm/lib:$LD_LIBRARY_PATH"
User=dd-agent
Restart=on-failure
ExecStart=/opt/datadog-agent/bin/agent/agent run -p /opt/datadog-agent/run/agent.pid

[Install]
WantedBy=multi-user.target

Here’s an example of the upstart config:

description "Datadog Agent"

start on started networking
stop on runlevel [!2345]

respawn
respawn limit 10 5
normal exit 0

console log
env DD_LOG_TO_CONSOLE=false
env LD_LIBRARY_PATH=/opt/mqm/lib64:/opt/mqm/lib:$LD_LIBRARY_PATH

setuid dd-agent

script
  exec /opt/datadog-agent/bin/agent/agent start -p /opt/datadog-agent/run/agent.pid
end script

post-stop script
  rm -f /opt/datadog-agent/run/agent.pid
end script

Each time there is an agent update, these files are wiped and will need to be updated again.

Alternatively, if you are using Linux, after the MQ Client is installed ensure the runtime linker can find the libraries. For example, using ldconfig:

Put the library location in an ld configuration file.

sudo sh -c "echo /opt/mqm/lib64 > /etc/ld.so.conf.d/mqm64.conf"
sudo sh -c "echo /opt/mqm/lib > /etc/ld.so.conf.d/mqm.conf"

Update the bindings.

sudo ldconfig

Permissions and authentication

There are a number of ways to set up permissions in IBM MQ. Depending on how your setup works, create a datadog user within MQ with read only permissions.

Note: “Queue Monitoring” must be enabled and set to at least “Medium”. This can be done via the MQ UI or with an mqsc command:

> /opt/mqm/bin/runmqsc
5724-H72 (C) Copyright IBM Corp. 1994, 2018.
Starting MQSC for queue manager datadog.


ALTER QMGR MONQ(MEDIUM) MONCHL(MEDIUM)
     1 : ALTER QMGR MONQ(MEDIUM) MONCHL(MEDIUM)
AMQ8005I: IBM MQ queue manager changed.

       :
One MQSC command read.
No commands have a syntax error.
All valid MQSC commands were processed.

Configuration

  1. Edit the ibm_mq.d/conf.yaml file, in the conf.d/ folder at the root of your Agent’s configuration directory to start collecting your IBM MQ performance data. See the sample ibm_mq.d/conf.yaml for all available configuration options.

  2. Restart the Agent.

Metric collection

There are a number of options to configure IBM MQ, depending on how you’re using it.

channel: The IBM MQ channel queue_manager: The Queue Manager named host: The host where IBM MQ is running port: The port that IBM MQ has exposed

If you’re using a username and password setup, you can set the username and password.

If you’re using SSL Authentication, you can setup SSL Authentication.

And finally, the check only monitors the queues you have set in the config:

queues:
  - APP.QUEUE.1
  - ADMIN.QUEUE.1

Log collection

Available for Agent >6.0

  1. Collecting logs is disabled by default in the Datadog Agent, enable it in your datadog.yaml file:

      logs_enabled: true
  2. Next, point the config file to the proper MQ log files. You can uncomment the lines at the bottom of the MQ integration’s config file, and amend them as you see fit:

      logs:
        - type: file
          path: /var/mqm/log/<APPNAME>/active/AMQERR01.LOG
          service: <APPNAME>
          source: ibm_mq
          log_processing_rules:
            - type: multi_line
              name: new_log_start_with_date
              pattern: "\d{2}/\d{2}/\d{4}"
    
  3. Restart the Agent.

Validation

Run the Agent’s status subcommand and look for ibm_mq under the Checks section.

Data Collected

Metrics

ibm_mq.channel.channels
(gauge)
The number of active channels
Shown as resource
ibm_mq.channel.count
(gauge)
Sum by status to count channels. Filter by channel and status tags to create notifications.
ibm_mq.queue.service_interval
(gauge)
the time since last serviced
Shown as millisecond
ibm_mq.queue.inhibit_put
(gauge)
puts are inhibited
Shown as occurrence
ibm_mq.queue.depth_low_limit
(gauge)
the low limit on the depth to create an alert
Shown as item
ibm_mq.queue.inhibit_get
(gauge)
gets are inhibited
Shown as occurrence
ibm_mq.queue.harden_get_backout
(gauge)
number of times a message is retrieved
Shown as request
ibm_mq.queue.service_interval_event
(gauge)
is service necessary
Shown as occurrence
ibm_mq.queue.trigger_control
(gauge)
controls if trigger messages are written to an initiation queue
Shown as method
ibm_mq.queue.usage
(gauge)
what the queue is used for
Shown as resource
ibm_mq.queue.scope
(gauge)
controls if the queue exists in a cell directory
Shown as resource
ibm_mq.queue.type
(gauge)
the type of queue
Shown as resource
ibm_mq.queue.depth_max
(gauge)
the max depth of the queue
Shown as message
ibm_mq.queue.backout_threshold
(gauge)
backout threshold used by other applications
Shown as resource
ibm_mq.queue.depth_high_event
(gauge)
a depth high event has been generated
Shown as event
ibm_mq.queue.depth_low_event
(gauge)
a depth low event has been generated
Shown as event
ibm_mq.queue.trigger_message_priority
(gauge)
the message priority below which a message doesn't generate a trigger message
Shown as resource
ibm_mq.queue.depth_current
(gauge)
the number of messages in the queue
Shown as message
ibm_mq.queue.depth_max_event
(gauge)
controls whether queue full events are generated
Shown as event
ibm_mq.queue.open_input_count
(gauge)
the number of handles currently open
Shown as connection
ibm_mq.queue.persistence
(gauge)
the default persistance of messages on the queue
Shown as resource
ibm_mq.queue.trigger_depth
(gauge)
the number of messages on the queue before a trigger event is written
Shown as resource
ibm_mq.queue.max_message_length
(gauge)
the max length of a message
Shown as resource
ibm_mq.queue.depth_high_limit
(gauge)
the threshold against which the queue depth is compared before generated a queue high event
Shown as resource
ibm_mq.queue.priority
(gauge)
the default priority for messages on the queue
Shown as resource
ibm_mq.queue.input_open_option
(gauge)
the default way to open the queue for input
Shown as resource
ibm_mq.queue.message_delivery_sequence
(gauge)
the order in which messages will be returned after a get operation
Shown as resource
ibm_mq.queue.retention_interval
(gauge)
the period of time to retain the queue after elapsed it is elegible for deletion
Shown as hour
ibm_mq.queue.open_output_count
(gauge)
the number of handles that are available for adding messages
Shown as connection
ibm_mq.queue.trigger_type
(gauge)
the conditions under which trigger messages are written as a result of messages arriving on this queue
Shown as resource
ibm_mq.queue.depth_percent
(gauge)
the percent of the queue that is currently utilized
Shown as percent
ibm_mq.queue_manager.dist_lists
(gauge)
This indicates whether distribution-list messages can be placed on the queue
Shown as resource
ibm_mq.queue_manager.max_msg_list
(gauge)
the length of the longest message the queue manager can handle
Shown as byte
ibm_mq.queue.max_channels
(gauge)
the max number of channels that can be connected
Shown as connection
ibm_mq.queue.oldest_message_age
(gauge)
the age of the oldest message on the queue in seconds
Shown as second

Service Checks

ibm_mq.can_connect:
Returns CRITICAL if the Agent cannot connect to the MQ server for any reason, otherwise returns OK.

ibm_mq.queue_manager:
Returns CRITICAL if the Agent cannot retrieve stats from the queue manager, otherwise returns OK.

ibm_mq.queue:
Returns CRITICAL if the Agent cannot retrieve queue stats, otherwise returns OK.

ibm_mq.channel:
Returns CRITICAL if the Agent cannot retrieve channel stats, otherwise returns OK.

ibm_mq.channel.status:
Return CRITICAL if the status is INACTIVE/STOPPED/STOPPING. Returns OK if the status is RUNNING. Returns WARNING if the status might lead to running.

Events

IBM MQ does not include any events.

Troubleshooting

Need help? Contact Datadog support.

Further Reading

Additional helpful documentation, links, and articles:


Mistake in the docs? Feel free to contribute!