Topic alias MQTT : économiser de la bande passante sur les noms de topics longs

Un topic alias MQTT permet à un client d'envoyer une seule fois un nom de topic long, puis d'y faire référence par un entier de deux octets pendant le reste de la connexion. Sur des liens contraints comme le cellulaire, le backhaul LoRa ou le satellite, cela peut réduire de plus de moitié la taille des petits paquets de télémétrie. Ce guide explique comment se négocie le Topic Alias Maximum, comment calculer vos économies et comment utiliser correctement les aliases dans votre code.

Qu'est-ce qu'un topic alias MQTT

Les topic aliases font partie des fonctionnalités de MQTT 5 axées sur l'efficacité. En MQTT 3.1.1, chaque paquet PUBLISH transporte le nom complet du topic sous forme de chaîne UTF-8 précédée d'une longueur sur deux octets. Les arborescences de topics bien structurées, comme les chemins de style ISA-95, sont descriptives mais longues. Un chemin comme connectmq/factory1/production/line1/cnc1/telemetry compte 50 caractères, et si votre payload est un nombre de 20 octets avec un horodatage, le topic pèse plus de deux fois la taille des données.

Avec MQTT 5, l'émetteur peut ajouter une propriété Topic Alias (identifiant 0x23, entier sur deux octets) à un PUBLISH. La première fois, le paquet contient à la fois le nom complet du topic et l'alias, et le récepteur enregistre la correspondance. Les paquets PUBLISH suivants peuvent porter un nom de topic de longueur nulle accompagné de l'alias, et le récepteur substitue le topic enregistré.

Trois règles définissent la fonctionnalité :

1. Les aliases sont propres à chaque connexion et à chaque sens. La correspondance client vers broker et la correspondance broker vers client sont indépendantes. Les aliases ne font pas partie de l'état de session et sont oubliés à la déconnexion, même si la session persiste.
2. Chaque côté fixe un plafond. Le récepteur annonce combien d'aliases il acceptera avec la propriété Topic Alias Maximum (0x22). Une valeur de 0, ou l'absence de propriété, signifie que les aliases ne sont pas acceptés dans ce sens.
3. Les correspondances peuvent être remplacées. Envoyer un PUBLISH avec un numéro d'alias existant et un nom de topic non vide associe cet alias au nouveau topic.

Comment se négocie le Topic Alias Maximum

La négociation a lieu dans les paquets CONNECT et CONNACK :

Ainsi, si le CONNACK du broker indique 10, votre client peut utiliser les aliases 1 à 10 sur ses publications sortantes. Si votre CONNECT indique 0 ou omet la propriété, le broker vous enverra toujours les noms de topics complets. L'alias 0 n'est jamais valide.

Si un émetteur enfreint ces limites, par exemple en utilisant l'alias 11 alors que le maximum est 10, ou en envoyant un nom de topic vide avec un alias jamais défini, le récepteur ferme la connexion avec le reason code 0x94 Topic Alias invalid. La référence des reason codes MQTT répertorie ce code avec les autres que vous rencontrerez probablement en débogage.

Calculer les économies de bande passante

Pas besoin de laboratoire pour estimer les économies : la structure des paquets est fixe. Prenons une publication QoS 0 en MQTT 5 avec le topic de 50 caractères ci-dessus et un payload de 20 octets :

Après le premier message, chaque publication est plus petite de 47 octets, soit une réduction d'environ 63 % au niveau de la couche MQTT. La première publication coûte 3 octets supplémentaires, remboursés dès le deuxième message.

Gardez la vue d'ensemble à l'esprit. Les en-têtes TCP et IP ajoutent environ 40 octets par segment, et TLS ajoute par-dessus le surcoût de ses enregistrements. Sur un lien où vous envoyez un message par minute, ces coûts de transport et le trafic keep alive dominent, et les topic aliases changent à peine la facture. Sur un lien qui envoie beaucoup de petits messages par seconde, ou qui regroupe plusieurs messages dans un même segment TCP, le nom du topic représente une grande part de chaque octet et les aliases sont rentables. Le guide de la consommation de bande passante MQTT détaille le calcul complet par message, TLS compris.

Vous pouvez vérifier ces chiffres avec Wireshark : capturez sur le port 1883, appliquez le filtre d'affichage mqtt et comparez les champs Topic Length et Msg Len du premier et du deuxième PUBLISH de votre client.

Utiliser les topic aliases avec MQTT.js

MQTT.js prend en charge les aliases manuellement comme automatiquement. Voici l'approche manuelle sur le serveur MQTT public gratuit, réservé aux tests, qui rend le mécanisme visible :

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, // nous acceptons jusqu'à 10 aliases du 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) {
      // Première publication : nom de topic complet + alias pour établir la correspondance
      client.publish(TOPIC, payload, { properties: { topicAlias: 1 } });
    } else {
      // Publications suivantes : nom de topic vide, alias seul
      client.publish("", payload, { properties: { topicAlias: 1 } });
    }

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

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

Abonnez-vous depuis un autre terminal pour confirmer que le broker a résolu l'alias et délivre le topic complet aux subscribers :

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

Attribution automatique des aliases

Pour de vraies applications, laissez la bibliothèque gérer la correspondance :

const client = mqtt.connect("mqtts://broker.connectmq.com:8883", {
  clientId: "alias-auto-9c1e",
  protocolVersion: 5,
  autoAssignTopicAlias: true, // attribuer automatiquement des aliases aux nouveaux topics
  autoUseTopicAlias: true,    // réutiliser un alias existant quand le topic se répète
});

Avec ces options, MQTT.js suit les topics qui ont déjà un alias, reste dans la limite annoncée par le broker et revient aux noms de topics complets lorsqu'il n'a plus d'aliases disponibles. Dans votre code, vous continuez à publier avec des chaînes de topic normales.

Pièges et bonnes pratiques

Les topic aliases sont simples, mais quelques erreurs causent la plupart des problèmes :

• Réutiliser des aliases après une reconnexion. Les correspondances disparaissent quand la connexion TCP se ferme. Un code qui retient « l'alias 1 est mon topic de télémétrie » d'une reconnexion à l'autre enverra un alias non défini et sera déconnecté avec 0x94. Renvoyez toujours d'abord le topic complet à chaque nouvelle connexion.
• Ignorer la valeur du CONNACK. Ne codez jamais un maximum en dur. Lisez-le à chaque fois dans le CONNACK, car il peut varier selon les brokers, les offres et les versions.
• Attribuer des aliases à des topics rarement utilisés. Les aliases sont utiles pour les topics sur lesquels vous publiez souvent. Consacrer un emplacement d'alias à un topic publié une fois par jour ne rapporte rien.
• Intermédiaires qui réécrivent les paquets. Un nom de topic vide n'a de sens qu'accompagné de sa propriété d'alias. Les passerelles ou traducteurs de protocole qui suppriment les propriétés MQTT 5 peuvent casser ce mécanisme : testez donc l'intégralité du chemin réseau.
• Espérer des économies sur des flux à forte QoS. Les QoS 1 et 2 ajoutent des paquets d'acquittement que les aliases ne réduisent pas.

Une check-list rapide avant d'activer les aliases sur une flotte :

1. Vérifiez que la bibliothèque cliente prend en charge MQTT 5 et les topic aliases.
2. Journalisez le Topic Alias Maximum du broker au moment de la connexion.
3. Réinitialisez les tables d'aliases dans votre gestionnaire de reconnexion.
4. Capturez quelques paquets pour vérifier les économies d'octets attendues.
5. Surveillez les déconnexions 0x94 dans les journaux après le déploiement.

Les topic aliases sur ConnectMQ

ConnectMQ prend en charge MQTT 5.0 sur tous ses endpoints, y compris les topic aliases, ainsi que la session expiry, la message expiry et les shared subscriptions. Vous pouvez donc conserver des noms de topics descriptifs de style ISA-95 pour la lisibilité tout en envoyant des paquets compacts depuis des appareils contraints. Le tutoriel MQTT est un bon point de départ si vous concevez encore votre structure de topics, et le guide des conventions de nommage des topics aide à garder ces noms cohérents.

Essayer les topic aliases sur ConnectMQ

Expérimentez d'abord sur le serveur MQTT public gratuit, puis passez à un broker MQTT managé privé, avec TLS et vos propres identifiants, lorsque vous êtes prêt pour de vrais appareils. Inscrivez-vous sur app.connectmq.com pour créer un broker Serverless gratuit sans carte bancaire, ou lisez d'abord le guide pour choisir un broker MQTT cloud.

Questions fréquentes

Le topic alias MQTT est-il disponible en MQTT 3.1.1 ?

Non. Les topic aliases ont été introduits avec MQTT 5.0 et sont transportés sous forme de propriété PUBLISH, qui n'existe pas en 3.1.1. Le client et le broker doivent tous deux utiliser MQTT 5.

Les topic aliases survivent-ils à une reconnexion ?

Non. Les aliases appartiennent à la connexion réseau, pas à la session. Après toute reconnexion, l'émetteur doit republier le nom complet du topic avant d'utiliser l'alias.

Que signifie le reason code 0x94 ?

Il signifie Topic Alias invalid : l'émetteur a utilisé l'alias 0, un alias supérieur au Topic Alias Maximum du récepteur, ou un nom de topic vide avant que la correspondance ne soit définie. Corrigez la gestion des aliases et reconnectez-vous.

Les subscribers voient-ils l'alias ou le topic complet ?

Les subscribers voient le topic complet. Le broker résout l'alias côté entrant, et tout alias côté sortant est négocié séparément avec chaque subscriber.