Herramientas y control
TinyMQ incluye dos interfaces de control de primera clase: un dashboard web embebido en /dashboard y un binario CLI nativo llamado tmq. Ambos se conectan al broker a través de HTTP y no requieren ninguna autenticación especial.
El Dashboard interactivo
Visita http://localhost:7800/dashboard en cualquier navegador mientras el broker esté en ejecución para acceder a la interfaz web interactiva.
Capacidades del Dashboard
- Modo Auto-Refresh (se recarga automáticamente cada 3 s).
- Monitorización del uptime y del consumo de memoria.
- Indicadores visuales para los Active Webhooks y las Dead Letter Queues (DLQ).
- Interfaz de creación manual de topics.
- Seguimiento en tiempo real de los consumers en espera.
- Modo oscuro (soporte completo con temas CSS
data-theme). - Mapa de Topología del Cluster: Visualiza dinámicamente el cluster Raft, mostrando el estado del Leader y la salud en vivo de los nodos a través del enjambre.
- Publicador Embebido: Publica mensajes directamente desde la UI, soportando inputs de Prioridad, TTL y Delay.
- Internacionalización: Cambia entre 🇬🇧 inglés y 🇪🇸 español directamente en la UI.
- Paleta de comandos (
Ctrl+K/Cmd+K) — busca queues y ejecuta acciones rápidas (Publish, Consume, Tail) desde un diálogo flotante. - Columnas ordenables — haz clic en cualquier encabezado de columna (Queue Name, Messages, Consumers) para ordenar ascendente/descendente.
- Skeleton loaders — placeholders animados durante la carga inicial de datos.
- Resaltado de sintaxis JSON en los modales de peek/consume.
- Atajo
/— presiona/en cualquier lugar para enfocar instantáneamente el input de búsqueda/filtro de queues.
El dashboard muestra una cuadrícula de métricas en vivo y una tabla de topics ordenable. Toda la lógica se ejecuta en Vanilla JS — sin React, sin Vue, sin peso de bundle.
Cuadrícula de métricas:
| Tarjeta | Descripción |
|---|---|
| Uptime | Tiempo que lleva en ejecución el proceso del broker |
| Active Queues/Topics | Número total de topics con al menos un mensaje o un consumer en espera |
| Messages in RAM | Total de mensajes almacenados en todas las queues |
| Webhooks | Total de endpoints webhook registrados |
| Broker Memory | runtime.MemStats.Alloc de Go — heap real en uso |
Columnas de la tabla de topics:
| Columna | Descripción |
|---|---|
| Queue / Topic Name | Identificador del topic. Los topics DLQ se muestran con una etiqueta roja DLQ; los topics con webhook habilitado, con una etiqueta naranja Webhook |
| Waiting Consumers | Número de consumers en long-polling actualmente bloqueados en este topic |
| Messages in RAM | Número actual de mensajes en la queue |
| Actions | Botones en línea: Publish, Consume (Pop), 👁️ Peek, Purge, Delete |
Auto-Refresh
Activa Auto-Refresh en la barra de control superior. Cuando está habilitado, la página se recarga cada 3 segundos. La configuración se guarda en localStorage para que persista entre recargas de página.
El Auto-Refresh se pausa automáticamente cuando cualquier modal (Publish, Consume, Peek) está abierto, para evitar que la página se recargue mientras estás leyendo el resultado.
Acciones de gestión de queues
Puedes interactuar directamente con las queues desde el dashboard:
- Publish: Envía un payload (soporta TTL, Delay, Priority, Broadcast). Usa
POST /api/queues/publish. - Consume (Pop): Desencola inmediatamente un mensaje. Usa
GET /api/queues/consume. - Peek: Visualiza hasta 10 mensajes sin desencolarlos.
- Tail: Sigue en vivo un topic mediante SSE.
- Purge: Vacía una queue de todos sus mensajes.
- Delete: Elimina permanentemente la queue y su archivo WAL.
- Webhooks: Visualiza y gestiona los webhooks asociados al topic.
El CLI tmq
tmq es un panel de control basado en terminal para TinyMQ. Se conecta al broker a través de HTTP y presenta una salida con colores y alineación mediante tabwriter.
Instalación
Descárgalo desde GitHub Releases o instálalo vía Go:
go install github.com/x-name15/tinymq/cmd/tmq@latest
Configuración
Establece TINYMQ_URL para apuntar a un broker remoto:
export TINYMQ_URL=http://192.168.1.100:7800
(Por defecto es http://localhost:7800)
Si tu broker requiere autenticación, exporta la API key:
export TINYMQ_API_KEY=your_secret_key
Referencia de comandos
tmq status / tmq list
Muestra una tabla formateada con todos los topics activos, su número de mensajes, el número de consumers en espera, el tipo y el estado de webhook.
tmq status
tmq pub — Publicar un mensaje
# Basic publish
tmq pub orders.eu '{"user_id": 42, "item": "laptop"}'
# With TTL (expire in 5 minutes)
tmq pub orders.eu '{"user_id": 42}' --ttl=5m
# With delivery delay
tmq pub notifications '{"msg": "hello"}' --delay=10s
# Broadcast to all waiting consumers
tmq pub cache.invalidate '{"entity": "product"}' --broadcast
tmq sub — Consumir mensajes
# Consume one message (auto-acknowledged)
tmq sub orders.eu
# Wait up to 10s for a message if queue is empty (long-polling)
tmq sub orders.eu --timeout=10s
# Consume a batch of 5 messages
tmq sub orders.eu --limit=5
# Consume without auto-acknowledging (manual ACK required)
tmq sub orders.eu --auto-ack=false
tmq peek — Inspeccionar la RAM (sin destruir mensajes)
Lee mensajes de la queue sin eliminarlos. Seguro para depuración.
tmq peek orders.eu --limit=3
tmq tail — Modo espía en vivo
Transmite continuamente mensajes de un topic en tiempo real (usando SSE). Cada mensaje se imprime a medida que llega. Pulsa Ctrl+C para salir. Se reconecta automáticamente en caso de fallo.
tmq tail orders.eu
tmq top — Dashboard en vivo en la terminal
Abre un dashboard interactivo y auto-refrescante directamente en tu terminal. Limpia la pantalla y actualiza la lista de queues cada 2 segundos.
tmq top
tmq shell — REPL interactivo
Inicia una sesión interactiva donde puedes ejecutar comandos tmq sin escribir el prefijo tmq.
tmq shell
> status
> peek orders
> exit
tmq rm / tmq delete
Elimina una queue completamente a través de la API.
tmq rm orders.eu
tmq purge
Vacía todos los mensajes de una queue pero deja la queue intacta.
tmq purge orders.eu
tmq group
Administra Consumer Groups para mensajería Pub/Sub sin robo de mensajes. Esto puede ser usado como comando de nivel superior o dentro de tmq shell.
# Crear un consumer group en un topic
tmq group create orders.eu workers
# Listar todos los grupos de un topic
tmq group list orders.eu
tmq create — Provisionar un Topic
Provisiona explícitamente una queue mediante POST /api/topics. Útil para preconfigurar topics con políticas específicas antes de que llegue el primer mensaje.
# Crear un topic con la configuración por defecto
tmq create analytics.events
# Crear con política de desbordamiento y expiración automática de 24h en todos los mensajes
tmq create sensor.data --policy=drop-oldest --retention=24h
tmq cluster
Diagnostica y visualiza el estado de los peers cuando TinyMQ se ejecuta en modo de Alta Disponibilidad.
# View current node's cluster role and term
tmq cluster status
# List all known peers and their health
tmq cluster peers
# Continuously refresh peer table every 2 seconds
tmq cluster peers --watch
# Gracefully drain a node before maintenance (restarts, config changes)
# Note: always specify the target URL explicitly to avoid draining the wrong node
tmq cluster drain http://node-2:7800
tmq webhook
Gestiona los webhooks de un topic específico.
# List webhooks
tmq webhook list orders.eu
# Add a webhook
tmq webhook add orders.eu https://my-api.com/hook
tmq bench — Pruebas de carga
Ejecuta un benchmark de alta concurrencia contra el broker.
tmq bench --protocol=http --total=10000 --concurrency=50 --target=orders
Protocolos soportados: http, nats.
tmq backup & tmq restore
Realiza copias de seguridad y restaura los archivos de datos WAL del broker directamente desde el CLI.
# Create a backup archive (zip or tar.gz)
tmq backup my_backup.zip
#### `tmq restore`
Restaura los archivos de datos WAL del broker desde un archivo comprimido.
```bash
# Restore from an archive
tmq restore --file=my_backup.zip --data-dir=./data
tmq dlq redrive
Re-encola (redrive) todos los mensajes fallidos desde la DLQ de un topic (<topic>.dlq) de vuelta a la cola principal, reiniciando sus contadores de reintentos.
tmq dlq redrive orders.eu
tmq doctor
Ejecuta verificaciones locales de sanidad en el directorio de datos, puertos, variables de entorno y conectividad con el broker para diagnosticar problemas de configuración.
tmq doctor
Referencia rápida del CLI
tmq status
tmq top
tmq shell
tmq doctor
tmq create <topic> [--policy=reject|drop-oldest] [--retention=duration]
tmq pub <topic> <payload> [--ttl=duration] [--delay=duration] [--broadcast]
tmq sub <topic> [--timeout=duration] [--limit=count] [--auto-ack=true/false]
tmq peek <topic> [--limit=count]
tmq tail <topic>
tmq rm <topic>
tmq purge <topic>
tmq group list <topic>
tmq group create <topic> <group>
tmq dlq redrive <topic>
tmq cluster status
tmq cluster peers [--watch]
tmq cluster drain <node-url>
tmq webhook list <topic>
tmq webhook add <topic> <url>
tmq bench [--protocol=http|nats] [--total=10000] [--concurrency=50] [--target=<ip:port>]
tmq backup <filename>
tmq restore --file=<archive> --data-dir=<path>