Menu Fermer

Automatisation de la documentation des messages pour un wiki d’entreprise

Rédigé par Martin Führlinger, ingénieur en logiciel

TOUT SUR LE BUS DES MESSAGES

Bienvenue au 6ème article de cette série de billets de blog liés au bus de messages. Je recommande vivement de lire les autres aussi, afin d’obtenir le contexte complet. Ce sont les suivants :

Maintenant, je voudrais vous donner plus de détails sur notre documentation concernant les messages et la manière dont nous avons automatisé tout cela.

Documentation des messages

La documentation est difficile. Peu importe à qui vous demandez, la documentation est toujours difficile à créer et surtout à tenir à jour. Comme toujours, nous avons commencé par documenter nos messages dans l’espace de connaissance du wiki de notre entreprise. Chaque fois que de nouveaux messages étaient ajoutés ou que des messages existants étaient modifiés, quelqu’un devait les ajouter ou les mettre à jour. Les sujets des messages étaient énumérés dans une matrice, contenant le producteur, les sujets, les consommateurs et quelques notes supplémentaires. Voici à quoi cela ressemblait :

Wiki message matrix

Ce processus était lent et sujet à des erreurs. Nous voulions donc l’améliorer.

Comment automatiser la documentation

Au cours de l’une de nos journées des idées nouvelles (DONI), certains collègues et moi-même avons commencé à travailler sur un petit service permettant de documenter automatiquement les messages existants dans notre système. Nous avons mis au point un service assez simple, appelé MessageDoc, qui permet d’écouter tous les messages possibles, donc toutes les clés de routage (Pour plus de détails sur l’acheminement, cliquez ici), en écoutant « #.# ».

Chaque fois que nous recevons un message, nous l’analysons et stockons ses informations. Cela signifie que nous stockons un document dans un petit MongoDB contenant les métadonnées des messages, comme le producteur, le message lui-même et quelques autres attributs. Ceci est fait par sujet. Le diagramme suivant illustre le flux de réception et de stockage.

msg doc receive flow

Pour voir à quoi cela ressemble dans notre base de données, voici un exemple :

{
« _id » : « sample.updated.altered »,
« producteur » : « échantillons »,
« description » : «  »,
« consommateurs » : [
<liste des consommateurs&gt ;
],
« entités » : [ { {
« type » : « run_session »,
« updated_at » : ISODate(« 2020-11-11T14:56:02.304Z »),
« exemple » : <complete message payload&gt ;,
} ],
« version » : 4124,
« created_at » : ISODate(« 2019-11-28T11:15:26.105Z »),
« updated_at » : ISODate(« 2020-11-12T06:00:12.950Z »)
}

Comme nous ne voulons pas stocker chaque message, nous ne mettons à jour le contenu du message qu’une fois par jour. Nous avons parfois des messages polymorphiques. Cela signifie que nous envoyons différents types d’entités à l’intérieur d’un même type de message. Par exemple, un « sample_message » peut être de type « run_session », « sleep_session » ou autres. Nous ne stockons qu’un seul exemple par type d’entité.

Nous savons qui est le producteur d’un message, car il fait partie de la charge utile du message (voir comment nous avons défini le contenu de notre message). Chaque fois qu’un document est écrit à mongodb, nous mettons également à jour les consommateurs de manière asynchrone. Nous y sommes parvenus en interrogeant le API Rabbitmq via une requête HTTP (en utilisant le chemin de configuration), en l’analysant et en mettant à jour tous les consommateurs de tous nos messages stockés. Des détails sur les « consommateurs » peuvent être trouvés dans le premier article de blog dans cette série.

msg doc mash processing

Construire une interface Web simple

Pour pouvoir accéder aux informations stockées sans interroger directement la base de données, nous avons construit une interface web simple en plus de cela. Fondamentalement, la vue d’ensemble est similaire à la matrice précédente du wiki. Elle montre tous les sujets regroupés par le producteur.

msg doc overview

Lors de l’accès à un sujet, les détails du sujet sont affichés, avec à nouveau tous les consommateurs pour ce sujet spécifique. Cela signifie également que les consommateurs d’un sujet peuvent être différents dans l’affichage des détails, comme par exemple les messages « échantillons créés » sont consommés par d’autres services que les messages « échantillons mis à jour ». Cette vue détaillée du sujet permet également d’ajouter une description au sujet.

msg doch topic detail

Comme mentionné ci-dessus, nous stockons un exemple de message pour chaque sujet et chaque type d’entité une fois par jour. Ces derniers peuvent également être affichés en développant le lien de l’entité correspondante ci-dessous.

msg doc msg detail

Rendre obsolète la documentation manuelle des messages

Avec ce service en place, nous avons pu déprécier la documentation des messages dans le wiki. Même si nous supprimons les données stockées dans le service de documentation des messages, celui-ci recrée automatiquement toutes les informations. La seule chose qui serait perdue serait les descriptions supplémentaires par sujet qui ont été ajoutées manuellement. Ce simple service, avec moins de 1000 lignes de code au total, a rendu obsolète la documentation manuelle des messages et de leur contenu, et nous a facilité la vie.

***

Cet article a été rédigé par adidas Runtastic Tech Team et traduit par LesRameurs.com. Les produits sont sélectionnés de manière indépendante. LesRameurs.com perçoit une rémunération lorsqu’un de nos lecteurs procède à l’achat en ligne d’un produit mis en avant.