Documenting Events in Event Driven Microservices

[sumeet kumar]

Hi, 

There is a strong need of a framework that can facilitate documentation of event driven microservices. 

It should be able to:

1. Generating document for each event. 

2. Generate document for a microservice showing all input and output events.

3. Assemble all events in form of event chains corresponding to a business process.

This can lead to following:

3. Automated testing of microservices in isolation. 

4. Automated testing of complete business case across microservices. 

5. Help a new developer or team in getting started on a new microservice. 

6. Help a developer in troubleshooting a failed business case.

7. Help a new developer or architect understand the involvement of microservices participating in a business case. 

8. Automatic generation of UML showing event flow. 

Do you see value in such a framework? Is there any similar framework or work in progress that you know of? Is there any suggestion you would like to give?

[Peter]

Hi,

We are using .net framework for our microservices.

What we did was creating a messaging library per microservice containing the events and using xml comments to describe them.

The microservice has a reference to its own messaging library. Also the library is published to an internal github source allowing other services to consume them.

We are using rabbitmq for messaging. For every event that has an event handler implemented we register a topic for the microservice queue.

Regarding point 3 event chains, ever considered investigating sagas (https://msdn.microsoft.com/en-us/library/jj591569.aspx)?

HTH

Cheers,

Peter

Op woensdag 25 april 2018 13:59:06 UTC+2 schreef sumeet kumar:

[Chris Richardson]

Hi,

Great question.

Take a look at https://github.com/microservice-patterns/ftgo-application/tree/master/ftgo-order-service-contracts/src/main/resources/contracts/messaging and https://livebook.manning.com/#!/book/microservices-patterns/chapter-9

Essentially, the messaging API of the Order Service - the events that it publishes - are specified by example. 

This is done using https://cloud.spring.io/spring-cloud-contract/, which implements Consumer-Driven Contact testing.

The example events are used for two things:

1. Verifying that the publisher, e.g. Order Service, publishes correctly structured events
2. Verifying that the consumer can process correctly structured events.

The code is still work in progess  - ie one event :-) - but hopefully it conveys the idea.

Chris

--
You received this message because you are subscribed to the Google Groups "microservices" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microservices+unsubscribe@googlegroups.com.
To post to this group, send email to micros...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microservices/a24673ee-2f35-4890-a89d-34b6863f371c%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Learn microservices - http://learn.microservices.io

Microservices application platform http://eventuate.io

Consulting and training http://chrisrichardson.net

[sumeet kumar]

Hi Peter, 

A documented external messaging library is a good option while creating microservices or implementing sagas. 

But think of the case when someone, few years down the line wants to understand the saga you implemented or want to add a new service to this saga or alter it. Will it not become impossible without a document specifying what all microservcies are involved and what all events are generated in this saga and in which order? 

If an automated document can happen that not only documents the individual events, but goes a step further and documents the whole saga or generate UML diagrams of events, then it will help enterprise who have far complex products, embrace microservices more confidently

Regards

[Peter]

That is exactly the reason for our approach! At the moment we support two ways for communication between services (1) http rest (2) amqp messaging. We want our services to be as "auto discoverable" as possible. For api clients, developers, business users, etc.

Using the libraries there are a lot of ways for supporting generation of documentation. For now we are mainly using middleware, e.g. Consul for service registry and discovery. Consul also has a kvp store that we are using discovery of http endpoints. RabbitMQ for implemented event handlers for events supported by the specific usvc. This information could be used to create a graph representation of the platform for example.

All our services share a core library (nugettable) that handles the registration of the microservice with the middleware at the startup of the service. This way it would be fairly easy to implement something to create documentation in any required form. E.g. create a graph in Neo4j, register with a documentation service, or anything else that comes to mind.

It is a little abstract maybe, but if you would like more specifics please let me know. 

Cheers,

Peter

Op donderdag 26 april 2018 13:47:28 UTC+2 schreef sumeet kumar:

[sumeet kumar]

Thank you so much for taking out the time Chris. 

I understand that this is a good approach to reliably maintain the messaging contract and help the consumers in implementation. I will work on these lines. 

Regards

Sumeet

To unsubscribe from this group and stop receiving emails from it, send an email to microservice...@googlegroups.com.

To post to this group, send email to micros...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microservices/a24673ee-2f35-4890-a89d-34b6863f371c%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[sumeet kumar]

Thanks Peter, 

I think I understand the approach. Also I have got some pointers from Chris's mail. I will try to work on the pointers I got from you two and come up with something and later update on this thread. 

Regards

[Peter]

Hi Sumeet,

Any new insights you're able to share with us?

Cheers,

Peter

Op vrijdag 27 april 2018 13:02:40 UTC+2 schreef sumeet kumar: