Monitor self-hosted IBM MQ with OpenTelemetry

Install NRDOT collector

Download and install the NRDOT package for your Linux distribution. Replace <NRDOT_VERSION> with the latest release tag from the nrdot-collector-releases page (for example, v0.12.0).

• For Debian/Ubuntu:

  bash

  Copier

  $
  curl -LO https://github.com/newrelic/nrdot-collector-releases/releases/download/<NRDOT_VERSION>/nrdot-collector_<NRDOT_VERSION>_linux_amd64.deb
  $
  sudo dpkg -i nrdot-collector_<NRDOT_VERSION>_linux_amd64.deb

• For RHEL/Rocky/Amazon Linux:

  bash

  Copier

  $
  curl -LO https://github.com/newrelic/nrdot-collector-releases/releases/download/<NRDOT_VERSION>/nrdot-collector_<NRDOT_VERSION>_linux_amd64.rpm
  $
  sudo dnf install ./nrdot-collector_<NRDOT_VERSION>_linux_amd64.rpm

Configure NRDOT Collector

Configure the NRDOT Collector to gather IBM MQ metrics and send them to New Relic. This configuration handles three main jobs:

• Connect to your queue managers
• Clean up the data
• Ship the data to New Relic

1. To create the directory and collector configuration file with the required permissions, run:

   bash

   Copier

   $
   # Config directory — group-readable by nrdot only (it will hold secrets)
   $
   sudo install -d -o root -g nrdot -m 0750 /etc/nrdot-collector
   $
   
   $
   # Create the config file with correct permissions
   $
   sudo install -o root -g nrdot -m 0640 /dev/null /etc/nrdot-collector/ibmmq-config.yaml
   $
   sudo -u nrdot ${EDITOR:-vi} /etc/nrdot-collector/ibmmq-config.yaml

2. Paste the following configuration into the created configuration file, replacing the placeholders with your actual values:

   extensions:
     health_check:
       endpoint: 127.0.0.1:13133
   
   processors:
   
     filter/ibmmq-overhead:
       metrics:
         exclude:
           match_type: regexp
           metric_names:
             - "^go_.*"
             - "^process_.*"
             - "^promhttp_.*"
             - "^scrape_.*"
   
     filter/ibmmq-queues:
       metrics:
         datapoint:
           - 'attributes["queue"] != nil and IsMatch(attributes["queue"], "^SYSTEM\\.(ADMIN\\.|MQSC\\.|DEFAULT\\.|AUTH\\.|CHANNEL\\.|CHLAUTH\\.|CICS\\.|SYNCPOINT\\.|INTERNAL\\.|PENDING\\.|PROTECTION\\.|BROKER\\.|AMQP\\.|DOTNET\\.|REST\\.|RETAINED\\.|SELECTION\\.|DURABLE\\.|HIERARCHY\\.|DDELAY\\.)")'
           - 'attributes["queue"] != nil and IsMatch(attributes["queue"], "^SYSTEM\\.CLUSTER\\.(COMMAND|HISTORY)\\.QUEUE$")'
           - 'attributes["queue"] != nil and IsMatch(attributes["queue"], "^AMQ\\.")'
   
     resourcedetection:
       detectors: [env, ec2, system]
       system:
         resource_attributes:
           host.name:
             enabled: true
           host.id:
             enabled: true
   
     transform/ibmmq-cleanup:
       metric_statements:
         - context: resource
           statements:
             - delete_key(attributes, "server.address")
             - delete_key(attributes, "server.port")
             - delete_key(attributes, "url.scheme")
         - context: datapoint
           statements:
             # Rename the injected identity labels to their OTel dotted form — the
             # names New Relic's IBM MQ entity synthesis keys on. qmgr / queue stay raw.
             - set(attributes["target.name"], attributes["targetName"]) where attributes["targetName"] != nil
             - delete_key(attributes, "targetName")
             - set(attributes["cluster.name"], attributes["clusterName"]) where attributes["clusterName"] != nil
             - delete_key(attributes, "clusterName")
             - delete_key(attributes, "instance")
             - delete_key(attributes, "job")
   
     memory_limiter/ibmmq:
       check_interval: 1s
       limit_mib: 512
       spike_limit_mib: 256
   
     cumulativetodelta/ibmmq: {}
   
     batch/ibmmq:
       send_batch_size: 1000
       timeout: 200ms
   
   exporters:
   
     otlphttp/ibmmq:
       endpoint: ${env:NEW_RELIC_OTLP_ENDPOINT}
       headers:
         api-key: ${env:NEW_RELIC_LICENSE_KEY}
   
   receivers:
   
     prometheus/ibmmq-qm1:
       config:
         scrape_configs:
           - job_name: 'ibmmq-qm1'
             scrape_interval: ${env:IBMMQ_SCRAPE_INTERVAL:-60s}
             scrape_timeout: 15s
             static_configs:
               - targets:
                   - "${env:IBMMQ_QM1_ENDPOINT:-localhost:9157}"
                 labels:
                   targetName: "${env:TARGET_NAME}"
                   clusterName: "${env:IBMMQ_CLUSTER_NAME:-}"
   
   service:
     pipelines:
       metrics/ibmmq-qm1:
         receivers: [prometheus/ibmmq-qm1]
         processors:
           - filter/ibmmq-overhead
           - filter/ibmmq-queues
           - resourcedetection
           - transform/ibmmq-cleanup
           - memory_limiter/ibmmq
           - cumulativetodelta/ibmmq
           - batch/ibmmq
         exporters: [otlphttp/ibmmq]
   
     extensions: [health_check]

   Copier

What this configuration does

This configuration creates a pipeline that gathers metrics from IBM MQ queue managers and routes structured data to New Relic. Each component performs a specific function:

Each queue manager uses an independent pipeline so that an issue with one instance doesn't affect the others. The processor order is critical, don't reorder or remove processors, or metrics will fail to map correctly to IBM MQ entities.

Set NRDOT environment variables

Your collector configuration uses environment variables for deployment-specific values such as New Relic license key and queue manager endpoints. This approach keeps secrets separate from config files and makes it easy to adjust settings without editing YAML.

1. Create an environment file for the NRDOT collector:

   bash

   Copier

   $
   # Owner nrdot, mode 0600 — this file holds the license key
   $
   sudo install -o nrdot -g nrdot -m 0600 /dev/null /etc/nrdot-collector/ibmmq-env
   $
   sudo -u nrdot ${EDITOR:-vi} /etc/nrdot-collector/ibmmq-env

2. Add your value as KEY=VALUE lines to the file, replacing the placeholders with your actual values:

   # /etc/nrdot-collector/ibmmq-env
   
   # --- Required ---
   
   # New Relic ingest license key (40 chars, suffix NRAL)
   NEW_RELIC_LICENSE_KEY=<YOUR-LICENSE-KEY>
   
   # Stable host identity — first segment of every IBMMQ entity GUID
   TARGET_NAME=<YOUR-HOSTNAME>
   
   # mq-metric-samples exporter endpoints, one per queue manager
   IBMMQ_QM1_ENDPOINT=localhost:9157
   
   # --- Optional (shown with defaults) ---
   
   # OTLP endpoint: US prod default shown; For more information, refer to [New Relic OTLP endpoint](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp).
   NEW_RELIC_OTLP_ENDPOINT=https://otlp.nr-data.net:4318
   
   # Optional tag grouping for the IBMMQ_MANAGER entity (does not affect the entity GUID).
   # Leave unset to omit cluster.name (nullable); set it to group QMs under one cluster tag.
   # IBMMQ_CLUSTER_NAME=prod-mq-cluster
   
   # Scrape interval — must be >= the mq-metric-samples pollInterval (default 60s)
   IBMMQ_SCRAPE_INTERVAL=60s

   Copier

Set the following environment variables in your shell to verify the config before starting the collector:

Configure NRDOT systemd service

1. Create a systemd drop-in file to load the configuration and environment files.

   bash

   Copier

   $
   sudo mkdir -p /etc/systemd/system/nrdot-collector.service.d
   $
   sudo tee /etc/systemd/system/nrdot-collector.service.d/ibmmq.conf > /dev/null << 'EOF'
   $
   [Service]
   $
   EnvironmentFile=/etc/nrdot-collector/ibmmq-env
   $
   ExecStart=
   $
   ExecStart=/usr/bin/nrdot-collector --config /etc/nrdot-collector/ibmmq-config.yaml
   $
   MemoryMax=1G
   $
   LimitNOFILE=65536
   $
   NoNewPrivileges=true
   $
   ProtectSystem=strict
   $
   ProtectHome=true
   $
   EOF

   The empty ExecStart= line clears the default command, and the second line sets the custom command. This prevents the collector from starting twice. The other settings load the environment file, limit memory usage, and improve security.

2. After creating the drop-in, verify systemd can parse it without errors:

   bash

   Copier

   $
   sudo systemd-analyze verify /etc/systemd/system/nrdot-collector.service
   $
   # No output means no syntax errors

Start NRDOT collector and verify

1. Start the collector and enable it to run automatically on boot:

   bash

   Copier

   $
   sudo systemctl daemon-reload
   $
   sudo systemctl enable --now nrdot-collector.service
   $
   sudo systemctl status nrdot-collector.service --no-pager

   The status command should show Active: active (running). If you see Active: failed, check the logs with journalctl -u nrdot-collector.service -n 200 --no-pager.

2. Verify the collector is healthy:

   bash

   Copier

   $
   curl -sS http://127.0.0.1:13133
   $
   # Expected: {"status":"Server available", ...}

3. Confirm your IBM MQ metrics are flowing to New Relic. Wait for 60 seconds after the collector starts, then check your data using the verification queries in Find and query your data.

View your data in New Relic

Once your collector is running and metrics are flowing, you'll see your queue managers as IBMMQ_MANAGER entities in New Relic, with their queues as child IBMMQ_QUEUE entities. For details on finding your data, running queries, and setting up dashboards and alerts, see Find and query your data.