Home Fitness Training Automating Message Documentation for a Company Wiki

Automating Message Documentation for a Company Wiki

9 min read

Written by Martin Führlinger, Software Engineer Backend


Welcome to the sixth put up on this message bus associated weblog put up collection. I extremely advocate studying the others too, to get the complete context. These are: 

Now, I wish to present extra insights into our documentation round messages and the way we automated this.

Message Documentation

Documentation is tough. No matter who you ask, documentation is all the time exhausting to create and most vital hold updated. As all the time, we started with documenting our messages in our firm wiki’s information house. Whenever new messages have been added or present ones modified, somebody had so as to add or replace them. The message subjects have been listed in a matrix, containing the producer, the subjects, the shoppers, and a few extra notes. It seemed like this:

Wiki message matrix

This course of was sluggish and error-prone. So we wished to enhance this. 

How to Automate Documentation 

During considered one of our Day of New Ideas (DONIs), some colleagues and myself started to work on a small service to mechanically doc the prevailing messages in our system. We got here up with a fairly easy service, named MessageDoc, simply listening to all potential messages, so to all routing keys (find details about routing here), by listening to `#.#`.

Whenever we obtain a message, we parse it and retailer its info. This means we retailer a doc in a small MongoDB containing the messages meta knowledge, just like the producer, the message itself and a few extra attributes. This is completed per matter. The stream of receiving and storing will be seen within the following diagram.

msg doc receive flow

To see how this appears like in our database, right here is an instance: 

  "_id" : "sample.updated.altered",
  "producer" : "samples",
  "description" : "",
  "consumers" : [
    <list of consumers>
  "entities" : [ {
    "type" : "run_session",
    "updated_at" : ISODate("2020-11-11T14:56:02.304Z"),
    "example" : <full message payload>,
  } ],
  "version" : 4124,
  "created_at" : ISODate("2019-11-28T11:15:26.105Z"),
  "updated_at" : ISODate("2020-11-12T06:00:12.950Z")

As we don’t wish to retailer each single message, we solely replace the message’s content material as soon as a day. We typically have polymorphic messages. This means we’re sending several types of entities inside the identical message sort. For occasion, a “sample_message” will be of sort “run_session”, “sleep_session” or others. We retailer just one instance per entity sort.

We know who the producer of a message is, as it’s a part of the message payload (see how we defined our message content). Whenever a doc is written to mongodb, we additionally replace the shoppers asynchronously. We achieved this by querying the Rabbitmq API configuration through a HTTP request (utilizing the all-configuration path), parsing it and updating all shoppers of all our saved messages. Details about “consumers” will be discovered within the first blog post on this collection.

msg doc mash processing

Building a easy Web-Interface

To be capable to entry the saved info with out querying the database immediately, we constructed a easy internet interface on high of this. Basically, the overview appears just like the earlier matrix within the wiki. It reveals all subjects grouped collectively by the producer.

msg doc overview

When accessing a matter, the subject particulars are proven, with all of the shoppers once more for this particular matter. This additionally means the shoppers of a matter will be totally different within the particulars view, as e.g.”samples.created.accomplished” messages are consumed by different providers than “samples.up to date.altered”. This matter element view additionally permits so as to add some description to the subject.

msg doch topic detail

As talked about above, we retailer an instance message for each matter and each entity sort as soon as a day. These will be proven too by increasing the corresponding entity link under.

msg doc msg detail

Making Manual Message Documentation Obsolete 

With this service in place, we have been capable of deprecate the message documentation within the wiki. Even if we delete knowledge saved within the message doc service, it’s mechanically recreating all the data. The solely factor which might be misplaced are the extra descriptions per matter which have been added manually. This easy service, with lower than 1000 strains of code total, made handbook documentation of messages and its content material out of date, and our life simpler. 



Source link

Load More Related Articles
Load More By Neil Johnson
Load More In Fitness Training

Leave a Reply

Your email address will not be published. Required fields are marked *

Check Also

The 15 Best CBD Oils You Need to Consider Trying In 2021

This article was produced by Kamadeva Yoga.  With 2021 coming proper across the nook, we’r…