Logging Markdown with Java

test output with markdown formatting

Logging can be a pain. Reading logs can be an even bigger pain. Especially if you spend a huge part of your time analysing a systems behaviour.

I often found myself in a situation where I avoided going through existing log files. Just because they were so ugly that I couldn’t find the motivation to start extracting valuable information from them.

Why Markdown?

First of all, the markdown syntax is super easy to learn and easy to read. It’s beautiful to look at, even if only displayed as monospaced text (e.g. in the console of your CI server). If exported and rendered (e.g. in your version control system), you can hand it to your supervisor as-is.

The test output from the example above looks like a hand-crafted performance report if rendered:

test output rendered by GitHub

Why all the efforts?

Because the time spent creating readable logs will reduce the time spent actually reading these logs. Similar to the economics of refactoring.

And don’t worry, you don’t have to fiddle with a bunch of syntax strings to create valid markdown. The Java Markdown Generator library contains helper classes that are frequently used in our projects, they will do all the hard work for you. Most elements can be created in-line:

You can use the library for creating headings, links, images, block quotes, code, lists and even tables. Example code for all of these markdown elements can be found in the GitHub repository.

Bonus

If you want to go all-in, you can let your own classes implement the MarkdownSerializable interface. This will come in handy for serializing whole objects with one line of code (e.g. a custom matrix instance serialized as markdown table).

test output being generated