Logs are hard to get right. Typically, people want do debug issues using them. Debugging is messy so logs become a mess.
Structured logging allows to clean up the mess a little bit. It even allows to draw a graph of an event type from logs in Kibana and similar instruments with ease.
Structured logging is even harder to get right than regular logs. But if you look at ways you can perceive a log, it becomes clear how a good log should look like.
- A log is a WAL of a database. Statements of the log are INSERT queries to several different tables. For example, there could be a table with operation timings, a table with a status of related services, a table with the results of tasks.
- A log is a code. The principles of YAGNI and DRY apply to it.
- A log is a stream of events. This means that ideally there should be only two types of entries in the log:
- The emergence of a new entity (preferably with an identifier).
- А departure of the entity from the scope (it was successfully saved, successfully returned to the client, not processed due to an error).
- A log is a history. Same story as the history of commits in Git. The commit message should say what happened and why. To see how it was done you need to look in a diff. Application logs should also say what happened and why. Good commit message format is described in detail a long ago.
- A log is NOT a story with plot twists. Records should not have ambiguous interpretations. There should be no meaning embedded in punctuation.
Check out Guide to structured logging in Go for practical application of those insights.