IBM MQ continúa siendo una tecnología fundamental en muchas arquitecturas empresariales donde las aplicaciones necesitan intercambiar mensajes de manera segura, confiable y asíncrona.
Si trabajas como administrador de middleware, Production Support, DevOps o SRE, conocer los principales comandos de IBM MQ puede ayudarte a identificar y resolver rápidamente problemas relacionados con Queue Managers, queues, channels, listeners y mensajes.
En esta guía veremos algunos de los comandos que considero más útiles en la administración diaria de IBM MQ sobre Linux/Unix.
1. Mostrar los Queue Managers
Uno de los primeros comandos que debemos conocer es:
dspmq
Ejemplo:
QMNAME(QM_PROD) STATUS(Running)
QMNAME(QM_TEST) STATUS(Ended normally)
También podemos consultar información de un Queue Manager específico:
dspmq -m QM_PROD
Este comando nos permite comprobar rápidamente si el Queue Manager se encuentra ejecutándose.
2. Iniciar un Queue Manager
strmqm QM_PROD
Después podemos comprobar su estado:
dspmq -m QM_PROD
Resultado esperado:
QMNAME(QM_PROD) STATUS(Running)
3. Detener un Queue Manager
Una parada controlada puede realizarse con:
endmqm QM_PROD
Una opción habitual es:
endmqm -w QM_PROD
-w espera a que el Queue Manager termine antes de devolver el control al shell.
IBM MQ también dispone de modos de terminación más agresivos, pero en producción no deberían utilizarse automáticamente sin entender el impacto sobre aplicaciones, transacciones y mensajes.
4. Entrar a MQSC
Una de las herramientas más importantes para un administrador IBM MQ es runmqsc.
runmqsc QM_PROD
Después veremos:
Starting MQSC for queue manager QM_PROD.
Ahora podemos ejecutar comandos MQSC como:
DISPLAY QMGR
Para salir:
END
También podemos utilizar:
QUIT
5. Mostrar información del Queue Manager
Dentro de runmqsc:
DISPLAY QMGR
Para mostrar todos los atributos:
DISPLAY QMGR ALL
Esto proporciona información importante sobre la configuración del Queue Manager.
6. Mostrar todas las queues
DISPLAY QUEUE(*)
Forma abreviada:
DIS Q(*)
Sin embargo, en ambientes grandes puede generar mucha información.
Para consultar una queue específica:
DISPLAY QLOCAL(APP.REQUEST.Q)
Forma abreviada:
DIS QL(APP.REQUEST.Q)
7. Revisar la profundidad de una queue
Uno de los comandos más importantes para Production Support:
DISPLAY QLOCAL(APP.REQUEST.Q) CURDEPTH
Por ejemplo:
AMQ8409I: Display Queue details.
QUEUE(APP.REQUEST.Q)
TYPE(QLOCAL)
CURDEPTH(1250)
CURDEPTH indica cuántos mensajes existen actualmente en la queue.
También resulta útil revisar:
DISPLAY QLOCAL(APP.REQUEST.Q) CURDEPTH MAXDEPTH
Por ejemplo:
CURDEPTH(1250)
MAXDEPTH(5000)
Esto permite determinar qué tan cerca se encuentra la queue de su capacidad máxima.
8. Revisar procesos conectados a una queue
Cuando una queue comienza a crecer, queremos saber si existen productores y consumidores.
DISPLAY QSTATUS(APP.REQUEST.Q) IPPROCS OPPROCS CURDEPTH
Los atributos principales son:
IPPROCS
Número de aplicaciones que tienen la queue abierta para input.
OPPROCS
Número de aplicaciones que tienen la queue abierta para output.
Ejemplo:
CURDEPTH(5000)
IPPROCS(0)
OPPROCS(3)
Esto es una pista muy importante.
Tenemos productores enviando mensajes, pero aparentemente ningún consumidor procesándolos.
9. Mostrar todas las local queues
DISPLAY QLOCAL(*)
Forma abreviada:
DIS QL(*)
Queues remotas:
DISPLAY QREMOTE(*)
Alias:
DISPLAY QALIAS(*)
10. Revisar una Transmission Queue
En arquitecturas distribuidas IBM MQ, las transmission queues son fundamentales.
DISPLAY QLOCAL(QM_REMOTE.XMITQ) CURDEPTH
Si la CURDEPTH comienza a crecer, puede existir un problema con el sender channel o con la conectividad hacia el Queue Manager remoto.
Un flujo conceptual sería:
Application
↓
Remote Queue
↓
Transmission Queue
↓
Sender Channel
↓
Network
↓
Receiver Channel
↓
Remote Queue Manager
↓
Local Queue
11. Mostrar channels
DISPLAY CHANNEL(*)
Forma abreviada:
DIS CHL(*)
Consultar un channel:
DISPLAY CHANNEL(TO.QM_REMOTE)
Para conocer el estado de channels activos:
DISPLAY CHSTATUS(*)
o:
DIS CHS(*)
12. Consultar un channel específico
DISPLAY CHSTATUS(TO.QM_REMOTE)
Podemos encontrar estados como:
RUNNING
RETRYING
STOPPED
INACTIVE
BINDING
INITIALIZING
Para troubleshooting, RETRYING es especialmente importante.
Si encontramos:
STATUS(RETRYING)
debemos investigar por qué el sender channel no logra establecer o mantener la comunicación.
13. Iniciar un channel
START CHANNEL(TO.QM_REMOTE)
Después:
DISPLAY CHSTATUS(TO.QM_REMOTE)
14. Detener un channel
STOP CHANNEL(TO.QM_REMOTE)
En producción debemos entender primero el impacto, ya que detener un channel puede interrumpir el flujo de mensajes entre Queue Managers.
15. Revisar la conexión del channel
Un comando muy útil:
DISPLAY CHSTATUS(TO.QM_REMOTE) ALL
También podemos enfocarnos en determinados atributos:
DISPLAY CHSTATUS(TO.QM_REMOTE) STATUS CONNAME XMITQ
Esto nos ayuda a relacionar:
Channel
↓
Connection
↓
Transmission Queue
16. Listeners
Mostrar listeners:
DISPLAY LISTENER(*)
Consultar su estado:
DISPLAY LSSTATUS(*)
Listener específico:
DISPLAY LSSTATUS(LISTENER.TCP)
17. Iniciar un listener
START LISTENER(LISTENER.TCP)
Detenerlo:
STOP LISTENER(LISTENER.TCP)
18. Revisar conexiones al Queue Manager
DISPLAY CONN(*)
Este comando puede generar bastante información en sistemas grandes.
También podemos utilizar:
DISPLAY CONN(*) TYPE(CONN)
Para troubleshooting, las conexiones permiten investigar qué aplicaciones o procesos están conectados al Queue Manager.
19. Revisar el estado de una queue
Uno de mis comandos favoritos para troubleshooting:
DISPLAY QSTATUS(APP.REQUEST.Q) ALL
O solamente los atributos que necesitamos:
DISPLAY QSTATUS(APP.REQUEST.Q) CURDEPTH IPPROCS OPPROCS
Esto proporciona rápidamente una imagen de:
Mensajes
+
Productores
+
Consumidores
20. Consultar mensajes sin desarrollar una aplicación
IBM MQ proporciona amqsbcg, una utilidad de ejemplo muy conocida para examinar mensajes.
amqsbcg APP.REQUEST.Q QM_PROD
Puede ser útil para troubleshooting porque permite navegar mensajes sin consumirlos como lo haría una aplicación normal.
En producción debemos tener cuidado al mostrar mensajes porque pueden contener información sensible.
21. Colocar un mensaje de prueba
Otra utilidad de ejemplo:
amqsput APP.REQUEST.Q QM_PROD
Escribimos:
Test message from Folken IT
Presionamos Enter y posteriormente una línea vacía para terminar.
22. Leer mensajes
amqsget APP.REQUEST.Q QM_PROD
Atención: a diferencia de browsing, amqsget puede consumir/eliminar mensajes de la queue.
Por esa razón:
amqsbcg
y:
amqsget
no deben confundirse durante troubleshooting en producción.
23. Revisar Dead Letter Queue
Primero podemos identificar la DLQ configurada:
DISPLAY QMGR DEADQ
Por ejemplo:
DEADQ(SYSTEM.DEAD.LETTER.QUEUE)
Después:
DISPLAY QLOCAL(SYSTEM.DEAD.LETTER.QUEUE) CURDEPTH
Si CURDEPTH es mayor que cero, debemos investigar por qué existen mensajes que MQ no pudo entregar correctamente.
24. Error logs del Queue Manager
En Linux/Unix, una ubicación habitual de los errores del Queue Manager es:
/var/mqm/qmgrs/<QMGR>/errors/
Archivos típicos:
AMQERR01.LOG
AMQERR02.LOG
AMQERR03.LOG
Por ejemplo:
tail -100 /var/mqm/qmgrs/QM_PROD/errors/AMQERR01.LOG
Seguirlo:
tail -f /var/mqm/qmgrs/QM_PROD/errors/AMQERR01.LOG
Estos logs son fundamentales para investigar errores de channels, seguridad, recursos, networking y otros componentes de MQ.
25. Crear una local queue
Dentro de runmqsc:
DEFINE QLOCAL(APP.REQUEST.Q)
Con atributos:
DEFINE QLOCAL(APP.REQUEST.Q) MAXDEPTH(10000) DEFPSIST(YES)
26. Modificar una queue
ALTER QLOCAL(APP.REQUEST.Q) MAXDEPTH(20000)
Verificar:
DISPLAY QLOCAL(APP.REQUEST.Q) MAXDEPTH
27. Limpiar una queue
IBM MQ permite eliminar todos los mensajes de una local queue:
CLEAR QLOCAL(APP.REQUEST.Q)
Este es un comando que debes tratar con muchísimo cuidado.
En producción:
CLEAR QLOCAL(...)
puede provocar pérdida irreversible de mensajes.
Nunca debería utilizarse simplemente porque una queue tiene muchos mensajes.
Primero debemos entender por qué está creciendo.
28. Comandos que deberías memorizar
Si estás comenzando con IBM MQ, recomiendo dominar primero estos:
dspmq
strmqm QM_PROD
endmqm -w QM_PROD
runmqsc QM_PROD
Dentro de MQSC:
DISPLAY QMGR
DISPLAY QLOCAL(*)
DISPLAY QLOCAL(APP.Q) CURDEPTH MAXDEPTH
DISPLAY QSTATUS(APP.Q) CURDEPTH IPPROCS OPPROCS
DISPLAY CHANNEL(*)
DISPLAY CHSTATUS(*)
DISPLAY CHSTATUS(CHANNEL.NAME) ALL
DISPLAY LISTENER(*)
DISPLAY LSSTATUS(*)
DISPLAY CONN(*)
DISPLAY QMGR DEADQ
Y desde Linux:
tail -f /var/mqm/qmgrs/QM_PROD/errors/AMQERR01.LOG
Metodología para troubleshooting
Conocer comandos es importante, pero conocer el orden en que debemos investigar es todavía más importante.
Supongamos que una aplicación reporta:
“Los mensajes no están llegando al sistema remoto.”
Podemos investigar de esta manera:
¿Queue Manager está RUNNING?
↓
dspmq
↓
¿Está creciendo la application queue?
↓
CURDEPTH
↓
¿Existen consumidores?
↓
IPPROCS / OPPROCS
↓
¿Está creciendo la XMITQ?
↓
Transmission Queue
↓
¿Sender Channel está RUNNING?
↓
CHSTATUS
↓
¿Listener remoto está disponible?
↓
Listener / Network
↓
¿Existen errores?
↓
AMQERR01.LOG
↓
¿Hay mensajes en la DLQ?
↓
DEADQ
↓
Root Cause Analysis
Por ejemplo, si encontramos:
XMITQ CURDEPTH(15000)
CHANNEL STATUS(RETRYING)
ya tenemos una pista muy importante.
El problema probablemente no se encuentra en la aplicación productora.
Los mensajes están llegando al Queue Manager, pero MQ tiene dificultades para enviarlos al sistema remoto.
Ahora debemos investigar el channel, networking, DNS, listener, TLS, autenticación o disponibilidad del Queue Manager remoto.
La regla más importante
Cuando una queue comienza a crecer, no debemos asumir inmediatamente que:
“MQ está fallando.”
La profundidad de la queue es un síntoma.
La causa podría encontrarse en:
- la aplicación consumidora;
- un channel;
- networking;
- TLS;
- autenticación/autorización;
- el Queue Manager remoto;
- una base de datos utilizada por el consumidor;
- un sistema downstream;
- mensajes problemáticos;
- capacidad o rendimiento.
El trabajo de un administrador de IBM MQ no consiste únicamente en iniciar Queue Managers y limpiar queues.
Consiste en comprender el flujo completo del mensaje, identificar dónde se interrumpió y resolver el problema sin poner en riesgo los mensajes que todavía están en tránsito.
¿Cuantos queu managers te ha tocado administrar y que versiones?