Microservice Architecture
Supported by KongWriting better problem reports: 6 essential details
Let’s imagine that you have just cloned an application’s Github repository and have encountered a problem. For example, perhaps ./gradlew build is failing. Or, perhaps one of the application’s containers is failing to start. You need to ask for help. But what information should you include in the problem report?
In this post, I’ll answer that question from the perspective of a recipient of problem reports from users of a variety of platforms and applications including the Eventuate platform and platform.microservices.io. Many problem reports are quite thorough but sadly there are some that are remarkably vague. As a result, it can be difficult to diagnose the root cause.
To avoid any confusion, here are the details that I generally like to see in a problem report.
Git repository and commit + any changes that you have made
The first essential detail is the version of the code that you are attempting to use. The commit might seem obvious, especially if you have created a GitHub issue. But, new commits might have been added since you cloned the repository. Or, the repository might have multiple branches or tags. What’s more, you might report the problem outside of the repository, such as via Email or Slack. Consequently, your problem report should include the repository URL, the branch, and the commit.
Furthermore, if you have made changes to the code you should also describe them in your problem report.
A good way to describe the changes is to provide the output of git diff, e.g. git diff origin/master.
Steps to reproduce
The second essential detail to include in the problem report is the sequence of ‘commands’ that reproduce the problem. You might need to also describe how you ran the command(s). For example, Gradle tasks can be run from either the command line or within Intellij IDEA.
The error message + stack trace
Another essential detail is the complete error message that has been copy/pasted from the terminal window or test report. Also, if it’s a Java application, you should provide the complete stack trace (which includes the error message) since it will show the error’s location.
Logs
It’s also essential to include the output of the failing command and/or any log files. For example:
- Output of the command copy/pasted from the terminal window or from the test report
- If the application is containerized, container logs
- Other logs, such as a server log
In order to ensure that you don’t leave out any important details, you should provide the complete log files and test report files. One convenient way to do do this is by creating Github Gists.
The status of containers
If the application is containerized, it’s valuable to include the output of docker ps -a.
With the -a option, docker ps shows all containers, not just running containers.
Quite often a terminated container is a valuable clue.
Environment
Lastly, it’s important to describe your environment, which includes:
- Operating system, e.g. Windows, Mac, Linux
- Processor, e.g. Macs now come in two flavors, Intel and ARM
- Java version, e.g. the output of
java -version - Versions of other relevant tools, e.g.
docker versionanddocker-compose version
You could, for example, include the output of uname -a.
Summary
Please include the following essential details in your problem reports:
- Code version: repository URL, the branch, and the commit + any changes that you have made
- Steps to reproduce
- The error message + stack trace
- Command output and logs
- The status of containers
- Environment: operating system, processor, Java version, etc.
About Microservices.io
Microservices.io is brought to you by Chris Richardson. Experienced software architect, author of POJOs in Action, the creator of the original CloudFoundry.com, and the author of Microservices patterns.
Chris helps clients around the world adopt the microservice architecture through consulting engagements, and training workshops.
MICROSERVICES WORKSHOPS
Chris teaches comprehensive workshops for architects and developers that will enable your organization use microservices effectively.
Avoid the pitfalls of adopting microservices and learn essential topics, such as service decomposition and design and how to refactor a monolith to microservices.
Learn moreLEARN about microservices
Chris offers numerous other resources for learning the microservice architecture.
Get the book: Microservices Patterns
Read Chris Richardson's book:
Example microservices applications
Want to see an example? Check out Chris Richardson's example applications. See code
Remote consulting session
Got a specific microservice architecture-related question? For example:
- Wondering whether your organization should adopt microservices?
- Want to know how to migrate your monolith to microservices?
- Facing a tricky microservice architecture design problem?
Consider signing up for a two hour, highly focussed, consulting session.
Virtual bootcamp: Distributed data patterns in a microservice architecture
My virtual bootcamp, distributed data patterns in a microservice architecture, is now open for enrollment!
It covers the key distributed data management patterns including Saga, API Composition, and CQRS.
It consists of video lectures, code labs, and a weekly ask-me-anything video conference repeated in multiple timezones.
The regular price is $395/person but use coupon MECNPWNR to sign up for $120 (valid until May 16th, 2023). There are deeper discounts for buying multiple seats.
Learn how to create a service template and microservice chassis
Take a look at my Manning LiveProject that teaches you how to develop a service template and microservice chassis.
BUILD microservices
Consulting services
Engage Chris to create a microservices adoption roadmap and help you define your microservice architecture,
The Eventuate platform
Use the Eventuate.io platform to tackle distributed data management challenges in your microservices architecture.
Eventuate is Chris's latest startup. It makes it easy to use the Saga pattern to manage transactions and the CQRS pattern to implement queries.
ASSESS your architecture
Consulting services
Engage Chris to conduct an architectural assessment.
Join the microservices google group
Topics
Note: tagging is work-in-process
anti-patterns · application api · application architecture · architecting · architecture documentation · assemblage · beer · containers · dark energy and dark matter · deployment · design-time coupling · development · devops · docker · eventuate platform · glossary · hexagonal architecture · implementing commands · implementing queries · inter-service communication · kubernetes · loose coupling · microservice architecture · microservice chassis · microservices adoption · microservicesio updates · multi-architecture docker images · observability · pattern · refactoring to microservices · resilience · sagas · security · service api · service collaboration · service design · service discovery · service granularity · service template · software delivery metrics · success triangle · tacos · team topologies · transaction management · transactional messaging
