Alias de topic MQTT: ahorra ancho de banda con nombres de topic largos

Un alias de topic MQTT permite a un cliente enviar una sola vez un nombre de topic largo y, a partir de ahí, referirse a él con un entero de dos bytes durante el resto de la conexión. En enlaces limitados, como redes móviles, backhaul LoRa o satélite, eso puede reducir a menos de la mitad el tamaño de los paquetes pequeños de telemetría. Esta guía explica cómo se negocia el Topic Alias Maximum, cómo calcular tu ahorro y cómo usar correctamente los alias desde código.

Qué es un alias de topic MQTT

Los alias de topic son una de las funciones de MQTT 5 orientadas a la eficiencia. En MQTT 3.1.1, cada paquete PUBLISH lleva el nombre de topic completo como cadena UTF-8 con un prefijo de longitud de dos bytes. Los árboles de topics bien estructurados, como las rutas de estilo ISA-95, son descriptivos pero largos. Una ruta como connectmq/factory1/production/line1/cnc1/telemetry tiene 50 caracteres, y si tu payload es un número de 20 bytes con marca de tiempo, el topic ocupa más del doble que los datos.

Con MQTT 5, el emisor puede añadir a un PUBLISH una propiedad Topic Alias (identificador 0x23, un entero de dos bytes). La primera vez que lo hace, el paquete contiene tanto el nombre de topic completo como el alias, y el receptor registra la asociación. Los PUBLISH siguientes pueden llevar un nombre de topic de longitud cero más el alias, y el receptor sustituye el topic almacenado.

Tres reglas definen la función:

1. Los alias son por conexión y por sentido. La asociación de cliente a broker y la de broker a cliente son independientes. Los alias no forman parte del estado de sesión y se olvidan al desconectar, aunque la sesión persista.
2. Cada lado fija un límite. El receptor anuncia cuántos alias aceptará mediante la propiedad Topic Alias Maximum (0x22). Un valor 0, o la ausencia de la propiedad, significa que no se aceptan alias en ese sentido.
3. Las asociaciones se pueden sustituir. Enviar un PUBLISH con un número de alias existente y un nombre de topic no vacío vuelve a asociar ese alias al nuevo topic.

Cómo se negocia el Topic Alias Maximum

La negociación se produce en los paquetes CONNECT y CONNACK:

Así, si el CONNACK del broker indica 10, tu cliente puede usar los alias del 1 al 10 en sus publicaciones salientes. Si tu CONNECT indica 0 u omite la propiedad, el broker te enviará siempre nombres de topic completos. El alias 0 nunca es válido.

Si un emisor incumple estos límites, por ejemplo usando el alias 11 cuando el máximo es 10, o enviando un nombre de topic vacío con un alias que nunca se definió, el receptor cierra la conexión con el reason code 0x94 Topic Alias invalid. La referencia de reason codes de MQTT recoge este código junto con los demás que probablemente encontrarás al depurar.

Calcular el ahorro de ancho de banda

No necesitas un laboratorio para estimar el ahorro; la estructura del paquete es fija. Toma una publicación QoS 0 en MQTT 5 con el topic de 50 caracteres anterior y un payload de 20 bytes:

Tras el primer mensaje, cada publicación es 47 bytes más pequeña, una reducción de alrededor del 63 por ciento en la capa MQTT. La primera publicación cuesta 3 bytes extra, que se recuperan de inmediato con el segundo mensaje.

No pierdas de vista el panorama general. Las cabeceras TCP e IP añaden unos 40 bytes por segmento, y TLS añade la sobrecarga de sus registros. En un enlace en el que envías un mensaje por minuto, esos costes de transporte y el tráfico de keep alive dominan, y los alias de topic apenas mueven la factura. En un enlace que envía muchos mensajes pequeños por segundo, o que agrupa varios mensajes en un solo segmento TCP, el nombre del topic es una parte importante de cada byte y los alias compensan. La guía de consumo de ancho de banda MQTT recorre el cálculo completo por mensaje, incluido TLS.

Puedes verificar las cifras con Wireshark: captura en el puerto 1883, aplica el filtro de visualización mqtt y compara los campos Topic Length y Msg Len del primer y del segundo PUBLISH de tu cliente.

Usar alias de topic con MQTT.js

MQTT.js admite los alias tanto de forma manual como automática. Este es el enfoque manual contra el servidor MQTT público gratuito de broker.connectmq.com (solo para pruebas, no para datos de producción), que deja ver el mecanismo:

const mqtt = require("mqtt");

const TOPIC = "connectmq/demo/9c1e/factory1/production/line1/cnc1/telemetry";

const client = mqtt.connect("mqtts://broker.connectmq.com:8883", {
  clientId: "alias-demo-9c1e",
  protocolVersion: 5,
  properties: {
    topicAliasMaximum: 10, // aceptamos hasta 10 alias del broker
  },
});

client.on("connect", (connack) => {
  const brokerMax = connack.properties?.topicAliasMaximum ?? 0;
  console.log("Broker accepts topic aliases up to:", brokerMax);

  if (brokerMax < 1) {
    console.log("Aliases not available, publishing with full topic names");
  }

  let count = 0;
  const timer = setInterval(() => {
    const payload = JSON.stringify({ t: Date.now(), rpm: 1200 + count });

    if (brokerMax < 1) {
      client.publish(TOPIC, payload);
    } else if (count === 0) {
      // Primera publicación: topic completo + alias establece la asociación
      client.publish(TOPIC, payload, { properties: { topicAlias: 1 } });
    } else {
      // Publicaciones posteriores: topic vacío, solo el alias
      client.publish("", payload, { properties: { topicAlias: 1 } });
    }

    if (++count === 5) {
      clearInterval(timer);
      client.end();
    }
  }, 1000);
});

client.on("error", (err) => console.error("MQTT error:", err.message));

Suscríbete desde otra terminal para confirmar que el broker resolvió el alias y entrega el topic completo a los suscriptores:

mosquitto_sub -h broker.connectmq.com -p 1883 -i alias-watch-9c1e \
  -t "connectmq/demo/9c1e/#" -v -V mqttv5

Asignación automática de alias

En aplicaciones reales, deja que la librería gestione la asociación:

const client = mqtt.connect("mqtts://broker.connectmq.com:8883", {
  clientId: "alias-auto-9c1e",
  protocolVersion: 5,
  autoAssignTopicAlias: true, // asignar alias automáticamente a los topics nuevos
  autoUseTopicAlias: true,    // reutilizar un alias existente cuando el topic se repite
});

Con estas opciones, MQTT.js lleva el control de qué topics tienen ya alias, se mantiene dentro del máximo anunciado por el broker y recurre a nombres de topic completos cuando se queda sin alias. Tú sigues publicando con cadenas de topic normales en tu código.

Errores habituales y buenas prácticas

Los alias de topic son sencillos, pero unos pocos errores causan la mayoría de los problemas:

• Reutilizar alias tras una reconexión. Las asociaciones desaparecen cuando se cierra la conexión TCP. El código que recuerda "el alias 1 es mi topic de telemetría" entre reconexiones enviará un alias no definido y será desconectado con 0x94. Vuelve a enviar siempre primero el topic completo en cada nueva conexión.
• Ignorar el valor del CONNACK. Nunca fijes el máximo en el código. Léelo del CONNACK cada vez, porque puede variar entre brokers, planes y versiones.
• Asignar alias a topics poco usados. Los alias ayudan en los topics que publicas a menudo. Gastar un hueco de alias en un topic que publicas una vez al día no aporta nada.
• Intermediarios que reescriben paquetes. Un nombre de topic vacío solo tiene sentido junto con su propiedad de alias. Las pasarelas o traductores de protocolo que eliminan las propiedades de MQTT 5 pueden romperlo, así que prueba toda la ruta de red.
• Esperar ahorros en flujos con mucho QoS. QoS 1 y 2 añaden paquetes de acuse de recibo que los alias no reducen.

Una lista rápida antes de activar los alias en una flota:

1. Confirma que la librería cliente admite MQTT 5 y alias de topic.
2. Registra el Topic Alias Maximum del broker al conectar.
3. Reinicia las tablas de alias en tu manejador de reconexión.
4. Captura algunos paquetes para verificar el ahorro de bytes esperado.
5. Vigila las desconexiones con 0x94 en los registros tras el despliegue.

Alias de topic en ConnectMQ

ConnectMQ admite MQTT 5.0 en todos sus endpoints, incluidos los alias de topic, junto con la expiración de sesión, la expiración de mensajes y las suscripciones compartidas. Eso significa que puedes mantener nombres de topic descriptivos de estilo ISA-95 por legibilidad y aun así enviar paquetes compactos desde dispositivos limitados. El tutorial de MQTT es un buen punto de partida si todavía estás diseñando tu estructura de topics, y la guía de convenciones de nombres de topics ayuda a mantener esos nombres coherentes.

Prueba los alias de topic en ConnectMQ

Experimenta primero en el servidor MQTT público gratuito y pasa después a un broker MQTT gestionado privado, con TLS y tus propias credenciales, cuando estés listo para dispositivos reales. Regístrate en app.connectmq.com para crear un broker Serverless gratuito sin tarjeta de crédito, o lee antes la guía para elegir un broker MQTT en la nube.

Preguntas frecuentes

¿Está disponible el alias de topic en MQTT 3.1.1?

No. Los alias de topic se introdujeron en MQTT 5.0 y viajan como una propiedad de PUBLISH, que no existe en 3.1.1. Tanto el cliente como el broker deben usar MQTT 5.

¿Sobreviven los alias de topic a una reconexión?

No. Los alias pertenecen a la conexión de red, no a la sesión. Tras cualquier reconexión, el emisor debe volver a publicar el nombre de topic completo antes de usar el alias.

¿Qué significa el reason code 0x94?

Significa Topic Alias invalid: el emisor usó un alias 0, uno por encima del Topic Alias Maximum del receptor o uno con un nombre de topic vacío antes de que se definiera la asociación. Corrige la gestión de alias y vuelve a conectar.

¿Los suscriptores ven el alias o el topic completo?

Los suscriptores ven el topic completo. El broker resuelve el alias en el lado de entrada, y cualquier alias en el lado de salida se negocia por separado con cada suscriptor.